Skip to content

Commit

Permalink
feat(docs): docs changes (#2868)
Browse files Browse the repository at this point in the history 
* feat(docs): add example how to set locale (#2867)

* docs(guide): add an explanation for the installation guide (#2769)

* docs(guide): add an explanation for the installation guide

* docs(guide): add an explanation for the cli guide

* docs(guide): add support for cli output

* fix: change sort priority - cmdk (#2873)

* docs: remove unsupported props in range calendar and date range picker (#2881)

* chore(calendar): remove showMonthAndYearPickers from range calendar story

* docs(date-range-picker): remove showMonthAndYearPickers info

* docs(range-calendar): remove unsupported props

* docs: refactor typing in form.ts (#2882)

* chore(docs): supplement errorMessage behaviour in input (#2892)

* refactor(docs): revise NextUI Provider structure

* chore(docs): add updated tag

---------

Co-authored-by: Nozomi-Hijikata <116155762+Nozomi-Hijikata@users.noreply.github.com>
Co-authored-by: HaRuki <soccer_haruki15@me.com>
Co-authored-by: Kaben <carnoxen@gmail.com>
  • Loading branch information
@wingkwong @Nozomi-Hijikata
@kuri-sun @carnoxen
4 people committed May 4, 2024
1 parent 73d9695 commit dc24587
Show file tree
Hide file tree
Showing 11 changed files with 208 additions and 85 deletions.
20 changes: 20 additions & 0 deletions apps/docs/components/cmdk.tsx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -154,6 +154,16 @@ export const Cmdk: FC<{}> = () => {
}
};

const prioritizeFirstLevelItems = (a: SearchResultItem, b: SearchResultItem) => {
if (a.type === "lvl1") {
return -1;
} else if (b.type === "lvl1") {
return 1;
}

return 0;
};

const results = useMemo<SearchResultItem[]>(
function getResults() {
if (query.length < 2) return [];
Expand All @@ -165,12 +175,22 @@ export const Cmdk: FC<{}> = () => {
if (words.length === 1) {
return matchSorter(data, query, {
keys: MATCH_KEYS,
sorter: (matches) => {
matches.sort((a, b) => prioritizeFirstLevelItems(a.item, b.item));

return matches;
},
}).slice(0, MAX_RESULTS);
}

const matchesForEachWord = words.map((word) =>
matchSorter(data, word, {
keys: MATCH_KEYS,
sorter: (matches) => {
matches.sort((a, b) => prioritizeFirstLevelItems(a.item, b.item));

return matches;
},
}),
);

Expand Down
3 changes: 2 additions & 1 deletion apps/docs/config/routes.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -421,7 +421,8 @@
"key": "nextui-provider",
"title": "NextUI Provider",
"keywords": "api references, nextui, api, nextui provider",
"path": "/docs/api-references/nextui-provider.mdx"
"path": "/docs/api-references/nextui-provider.mdx",
"updated": true
}
]
}
Expand Down
2 changes: 1 addition & 1 deletion apps/docs/content/components/input/regex-validation.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ export default function App() {
variant="bordered"
isInvalid={isInvalid}
color={isInvalid ? "danger" : "success"}
errorMessage={isInvalid && "Please enter a valid email"}
errorMessage="Please enter a valid email"
onValueChange={setValue}
className="max-w-xs"
/>
Expand Down
2 changes: 1 addition & 1 deletion apps/docs/content/components/tabs/form.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ export default function App() {
const AppTs = `import {Tabs, Tab, Input, Link, Button, Card, CardBody, CardHeader} from "@nextui-org/react";
export default function App() {
const [selected, setSelected] = React.useState<string | number>("login");
const [selected, setSelected] = React.useState<React.Key>("login");
return (
<div className="flex flex-col w-full">
Expand Down
171 changes: 129 additions & 42 deletions apps/docs/content/docs/api-references/nextui-provider.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,80 +5,167 @@ description: API References for NextUI Provider

# NextUI Provider

API reference for the `NextUIProvider`.

------

Here's the API reference for the `NextUIProvider`.
## Import

<ImportTabs
commands={{
main: 'import {NextUIProvider} from "@nextui-org/react";',
individual: 'import {NextUIProvider} from "@nextui-org/system";',
}}
/>

## Usage

```jsx
import * as React from "react";
import {NextUIProvider} from "@nextui-org/react";

function App() {
return (
<NextUIProvider>
<YourApplication />
</NextUIProvider>
);
}
```

## Props

### navigate
<Spacer y={6}/>

`navigate` provides a client side router to all nested components such as Link, Menu, Tabs, Table, etc.
`navigate`

**type**: `((path: string) => void) | undefined`
- **Description**: Provides a client side router to all nested components such as Link, Menu, Tabs, Table, etc.
- **Type**: `((path: string) => void) | undefined`

### locale
<Spacer y={2}/>

The locale to apply to the children. The [BCP47](https://www.ietf.org/rfc/bcp/bcp47.txt) language code for the locale. By default, It is `en-US`.
`locale`

**type**: `string | undefined`
- **Description**: The locale to apply to the children.
- **Type**: `string | undefined`
- **Default**: `en-US`

### defaultDates

The default dates range that can be selected in the calendar.
Here's the supported locales. By default, It is `en-US`.

**type**: `{ minDate?: CalendarDate | undefined; maxDate?: CalendarDate | undefined; }`
```tsx
const localeValues = [
'fr-FR', 'fr-CA', 'de-DE', 'en-US', 'en-GB', 'ja-JP',
'da-DK', 'nl-NL', 'fi-FI', 'it-IT', 'nb-NO', 'es-ES',
'sv-SE', 'pt-BR', 'zh-CN', 'zh-TW', 'ko-KR', 'bg-BG',
'hr-HR', 'cs-CZ', 'et-EE', 'hu-HU', 'lv-LV', 'lt-LT',
'pl-PL', 'ro-RO', 'ru-RU', 'sr-SP', 'sk-SK', 'sl-SI',
'tr-TR', 'uk-UA', 'ar-AE', 'ar-DZ', 'AR-EG', 'ar-SA',
'el-GR', 'he-IL', 'fa-AF', 'am-ET', 'hi-IN', 'th-TH'
];
```

- minDate
Here's an example to set a Spanish locale.

The minimum date that can be selected in the calendar.
```tsx
"use client";

**type**: `CalendarDate | undefined`
import {type ReactNode} from "react";
import {NextUIProvider} from "@nextui-org/react";

**default**: `new CalendarDate(1900, 1, 1)`
export function AppProvider(props: AppProviderProps) {
const {children, className} = props;

- maxDate
return (
<NextUIProvider locale="es-ES" className={className}>
{children}
</NextUIProvider>
);
}

The maximum date that can be selected in the calendar.
interface AppProviderProps {
children: ReactNode;
className?: string;
}
```

**type**: `CalendarDate | undefined`
<Spacer y={2}/>

**default**: `new CalendarDate(2099, 12, 31)`
`defaultDates`

### createCalendar
- **Description**: The default dates range that can be selected in the calendar.
- **Type**: `{ minDate?: CalendarDate | undefined; maxDate?: CalendarDate | undefined; }`
- **Default**: `{ minDate: new CalendarDate(1900, 1, 1), maxDate: new CalendarDate(2099, 12, 31) }`

This function helps to reduce the bundle size by providing a custom calendar system.
<Spacer y={2}/>

By default, this includes all calendar systems supported by `@internationalized/date`. However,
if your application supports a more limited set of regions, or you know you will only be picking dates
in a certain calendar system, you can reduce your bundle size by providing your own implementation
of `createCalendar` that includes a subset of these Calendar implementations.
`createCalendar`

For example, if your application only supports Gregorian dates, you could implement a `createCalendar`
function like this:
- **Description**:
This function helps to reduce the bundle size by providing a custom calendar system.

```tsx
import {GregorianCalendar} from '@internationalized/date';

function createCalendar(identifier) {
switch (identifier) {
case 'gregory':
return new GregorianCalendar();
default:
throw new Error(`Unsupported calendar ${identifier}`);
}
}
```
By default, this includes all calendar systems supported by `@internationalized/date`. However,
if your application supports a more limited set of regions, or you know you will only be picking dates
in a certain calendar system, you can reduce your bundle size by providing your own implementation
of `createCalendar` that includes a subset of these Calendar implementations.

For example, if your application only supports Gregorian dates, you could implement a `createCalendar`
function like this:

```tsx
import {GregorianCalendar} from '@internationalized/date';

function createCalendar(identifier) {
switch (identifier) {
case 'gregory':
return new GregorianCalendar();
default:
throw new Error(`Unsupported calendar ${identifier}`);
}
}
```

This way, only GregorianCalendar is imported, and the other calendar implementations can be tree-shaken.

- **Type**: `((calendar: SupportedCalendars) => Calendar | null) | undefined`

<Spacer y={2}/>

`disableAnimation`

This way, only GregorianCalendar is imported, and the other calendar implementations can be tree-shaken.
- **Description**: Disables animations globally. This will also avoid `framer-motion` features to be loaded in the bundle which can potentially reduce the bundle size.
- **Type**: `boolean`
- **Default**: `false`

**type**: `((calendar: SupportedCalendars) => Calendar | null) | undefined`
<Spacer y={2}/>

`disableRipple`

- **Description**: Disables ripple effect globally.
- **Type**: `boolean`
- **Default**: `false`

<Spacer y={2}/>

`skipFramerMotionAnimations`

- **Description**:
Controls whether `framer-motion` animations are skipped within the application.
This property is automatically enabled (`true`) when the `disableAnimation` prop is set to `true`,
effectively skipping all `framer-motion` animations. To retain `framer-motion` animations while
using the `disableAnimation` prop for other purposes, set this to `false`. However, note that
animations in NextUI Components are still omitted if the `disableAnimation` prop is `true`.
- **Type**: `boolean`
- **Default**: Same as `disableAnimation`

---

## Types

### CalendarDate
`CalendarDate`

A [CalendarDate](https://react-spectrum.adobe.com/internationalized/date/CalendarDate.html) represents a date without any time components in a specific calendar system from `@internationalized/date`.
- **Description**: A [CalendarDate](https://react-spectrum.adobe.com/internationalized/date/CalendarDate.html) represents a date without any time components in a specific calendar system from `@internationalized/date`.
- **Type**: `import {CalendarDate} from '@internationalized/date';`

### SupportedCalendars

Expand Down
4 changes: 2 additions & 2 deletions apps/docs/content/docs/components/date-range-picker.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -348,7 +348,7 @@ import {I18nProvider} from "@react-aria/i18n";
### DateRangePicker Props

| Attribute | Type | Description | Default |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
|---------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------|
| label | `ReactNode` | The content to display as the label. | - |
| value | `RangeValue<CalendarDate \| CalendarDateTime \| ZonedDateTime>` \| `undefined` \| `null` | The current value of the date-range-picker (controlled). | - |
| variant | `flat` \| `bordered` \| `faded` \| `underlined` | The variant of the date input. | `flat` |
Expand All @@ -375,7 +375,7 @@ import {I18nProvider} from "@react-aria/i18n";
| selectorIcon | `ReactNode` | The icon to toggle the date picker popover. Usually a calendar icon. | |
| pageBehavior | `single` \| `visible` | Controls the behavior of paging. Pagination either works by advancing the visible page by visibleDuration (default) or one unit of visibleDuration. | `visible` |
| validate | `(value: { inputValue: string, selectedKey: React.Key }) => ValidationError ｜ true ｜ null ｜ undefined` | Validate input values when committing (e.g., on blur), and return error messages for invalid values. | - |
| visibleMonths | `number` | The number of months to display at once. Up to 3 months are supported. Passing a number greater than 1 will disable the `showMonthAndYearPickers` prop. | `1` |
| visibleMonths | `number` | The number of months to display at once. Up to 3 months are supported. | `1` |
| autoFocus | `boolean` | Whether the element should receive focus on render. | `false` |
| hourCycle | `12` \| `24` | Whether to display the time in 12 or 24 hour format. This is determined by the user's locale. | - |
| granularity | `day` \| `hour` \| `minute` \| `second` | Determines the smallest unit that is displayed in the date picker. Typically "day" for dates. | - |
Expand Down
4 changes: 2 additions & 2 deletions apps/docs/content/docs/components/input.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -108,7 +108,7 @@ You can add a description to the input by passing the `description` property.

### With Error Message

You can combine the `isInvalid` and `errorMessage` properties to show an invalid input.
You can combine the `isInvalid` and `errorMessage` properties to show an invalid input. `errorMessage` is only shown when `isInvalid` is set to `true`.

<CodeDemo title="With Error Message" files={inputContent.errorMessage} />

Expand Down Expand Up @@ -206,7 +206,7 @@ In case you need to customize the input even further, you can use the `useInput`
| defaultValue | `string` | The default value of the input (uncontrolled). | - |
| placeholder | `string` | The placeholder of the input. | - |
| description | `ReactNode` | A description for the input. Provides a hint such as specific requirements for what to choose. | - |
| errorMessage | `ReactNode` \| `((v: ValidationResult) => ReactNode)` | An error message for the input. | - |
| errorMessage | `ReactNode` \| `((v: ValidationResult) => ReactNode)` | An error message for the input. It is only shown when `isInvalid` is set to `true` | - |
| validate | `(value: string) => ValidationError ｜ true ｜ null ｜ undefined` | Validate input values when committing (e.g. on blur), and return error messages for invalid values. | - |
| startContent | `ReactNode` | Element to be rendered in the left side of the input. | - |
| endContent | `ReactNode` | Element to be rendered in the right side of the input. | - |
Expand Down
Loading

0 comments on commit dc24587

Please sign in to comment.