@mezzanine-ui/react 1.0.0-rc.5 → 1.0.0-rc.7

package/hooks/useWindowWidth.js

@@ -1,5 +1,19 @@
 import { useState, useEffect } from 'react';
 
+/**
+ * 追蹤目前視窗寬度的 Hook。
+ *
+ * 在元件掛載時以 `window.innerWidth` 初始化，並監聽 `resize` 事件持續更新，
+ * 元件卸載時自動移除監聽器。
+ *
+ * @example
+ * ```tsx
+ * import { useWindowWidth } from '@mezzanine-ui/react';
+ *
+ * const width = useWindowWidth();
+ * const isMobile = width !== undefined && width < 768;
+ * ```
+ */
 function useWindowWidth() {
     const [windowWidth, setWindowWidth] = useState(window.innerWidth);
     function handleResize() {

package/index.d.ts

@@ -84,6 +84,8 @@ export { default as Pagination, PaginationItem, PaginationJumper, PaginationPage
 export type { PaginationItemProps, PaginationItemType, PaginationJumperProps, PaginationPageSizeProps, PaginationProps, } from './Pagination';
 export { default as Section } from './Section';
 export type { SectionProps } from './Section';
+export { SectionGroup } from './Section';
+export type { SectionGroupProps } from './Section';
 export { default as Table, TableContext, TableDataContext, TableSuperContext, getCellAlignClass, getRowKey, useTableContext, useTableDataContext, useTableDataSource, useTableRowSelection, useTableSuperContext, type ColumnAlign, type FixedType, type HighlightMode, type SortOrder, type TableActionItem, type TableActions, type TableActionsBase, type TableActionsWithMinWidth, type TableBaseProps, type TableBulkActions, type TableBulkGeneralAction, type TableBulkOverflowAction, type TableCollectable, type TableColumn, type TableColumnBase, type TableColumnBaseWithMinWidthRequired, type TableColumnTitleMenu, type TableColumnWithDataIndex, type TableColumnWithDataIndexAndMinWidth, type TableColumnWithMinWidth, type TableColumnWithRender, type TableColumnWithRenderAndMinWidth, type TableContextValue, type TableDataContextValue, type TableDataSource, type TableDataSourceWithId, type TableDataSourceWithKey, type TableDraggable, type TableDraggableOnlyProps, type TableExpandable, type TableExpansionState, type TableNoDragOrPinProps, type TableNonResizableProps, type TableNonVirtualizedProps, type TablePinnableOnlyProps, type TableProps, type TableRecord, type TableResizableProps, type TableResizedColumnState, type TableRowSelection, type TableRowSelectionBase, type TableRowSelectionCheckbox, type TableRowSelectionRadio, type TableScroll, type TableSelectionMode, type TableSelectionState, type TableSize, type TableSortingState, type TableToggleable, type TableTransitionState, type TableVirtualizedProps, type UpdateDataSourceOptions, type UseTableDataSourceOptions, } from './Table';
 export { default as Tag, TagGroup } from './Tag';
 export type { TagGroupProps, TagProps, TagSize } from './Tag';
@@ -120,8 +122,8 @@ export { default as Cascader, CascaderPanel } from './Cascader';
 export type { CascaderOption, CascaderPanelProps, CascaderProps, CascaderSize, } from './Cascader';
 export { default as Select, SelectControlContext, SelectTrigger, SelectTriggerTags, } from './Select';
 export type { SelectControl, SelectProps, SelectTriggerInputProps, SelectTriggerProps, SelectTriggerTagsProps, SelectValue, } from './Select';
-export { default as Selection } from './Selection';
-export type { SelectionProps, SelectionPropsBase } from './Selection';
+export { default as SelectionCard } from './SelectionCard';
+export type { SelectionCardProps, SelectionCardPropsBase, } from './SelectionCard';
 export { default as Slider, useSlider } from './Slider';
 export type { RangeSliderProps, RangeSliderValue, SingleSliderProps, SingleSliderValue, SliderBaseProps, SliderComponentProps, SliderProps, SliderRect, SliderValue, UseRangeSliderProps, UseSingleSliderProps, UseSliderCommonProps, UseSliderProps, UseSliderResult, } from './Slider';
 export { default as Textarea } from './Textarea';
@@ -132,8 +134,8 @@ export { default as TimePicker, TimePickerPanel } from './TimePicker';
 export type { TimePickerPanelProps, TimePickerProps } from './TimePicker';
 export { default as TimeRangePicker, useTimeRangePickerValue, } from './TimeRangePicker';
 export type { TimeRangePickerProps, TimeRangePickerValue, UseTimeRangePickerValueProps, } from './TimeRangePicker';
-export { default as Switch } from './Toggle';
-export type { ToggleProps as SwitchProps, ToggleSize as SwitchSize, } from './Toggle';
+export { default as Toggle } from './Toggle';
+export type { ToggleProps, ToggleSize } from './Toggle';
 export { Upload, UploadItem, UploadPictureCard, Uploader } from './Upload';
 export type { UploadFile, UploadItemProps, UploadPictureCardProps, UploadProps, UploaderProps, } from './Upload';
 /**

package/index.js

@@ -31,7 +31,7 @@ export { default as ButtonGroup } from './Button/ButtonGroup.js';
 export { default as Cropper } from './Cropper/Cropper.js';
 export { default as Typography } from './Typography/Typography.js';
 export { BaseCardGeneric as BaseCard, FourThumbnailCardGeneric as FourThumbnailCard, QuickActionCardGeneric as QuickActionCard, SingleThumbnailCardGeneric as SingleThumbnailCard, ThumbnailGeneric as Thumbnail } from './Card/index.js';
-export { default as Selection } from './Selection/Selection.js';
+export { default as SelectionCard } from './SelectionCard/SelectionCard.js';
 export { default as DropdownAction } from './Dropdown/DropdownAction.js';
 export { default as DropdownItem } from './Dropdown/DropdownItem.js';
 export { default as DropdownItemCard } from './Dropdown/DropdownItemCard.js';
@@ -77,6 +77,7 @@ export { default as PaginationItem } from './Pagination/PaginationItem.js';
 export { default as PaginationJumper } from './Pagination/PaginationJumper.js';
 export { default as PaginationPageSize } from './Pagination/PaginationPageSize.js';
 export { default as Section } from './Section/Section.js';
+export { default as SectionGroup } from './Section/SectionGroup.js';
 export { Table } from './Table/Table.js';
 export { default as Tag } from './Tag/Tag.js';
 export { default as TagGroup } from './Tag/TagGroup.js';
@@ -115,7 +116,7 @@ export { default as TextField } from './TextField/TextField.js';
 export { default as TimePicker } from './TimePicker/TimePicker.js';
 export { default as TimePickerPanel } from './TimePicker/TimePickerPanel.js';
 export { default as TimeRangePicker } from './TimeRangePicker/TimeRangePicker.js';
-export { default as Switch } from './Toggle/Toggle.js';
+export { default as Toggle } from './Toggle/Toggle.js';
 export { default as Upload } from './Upload/Upload.js';
 export { default as UploadItem } from './Upload/UploadItem.js';
 export { default as UploadPictureCard } from './Upload/UploadPictureCard.js';

package/llms.txt

@@ -0,0 +1,200 @@
+# @mezzanine-ui/react
+
+> React component library for Mezzanine UI — a comprehensive set of accessible, themeable components built on top of @mezzanine-ui/core, @mezzanine-ui/icons, and @mezzanine-ui/system.
+
+## Installation
+
+```bash
+npm install @mezzanine-ui/react @mezzanine-ui/core @mezzanine-ui/icons @mezzanine-ui/system react react-dom lodash
+```
+
+Peer dependencies: `react >= 18`, `react-dom >= 18`, `lodash >= 4`
+
+## Related Packages
+
+| Package                  | Role                                              |
+| ------------------------ | ------------------------------------------------- |
+| `@mezzanine-ui/core`     | CSS styles and TypeScript type definitions        |
+| `@mezzanine-ui/icons`    | SVG icon definitions (plain objects)              |
+| `@mezzanine-ui/system`   | Design tokens: palette, spacing, typography, etc. |
+
+## Import Patterns
+
+Individual component (preferred for tree-shaking):
+```ts
+import Button from '@mezzanine-ui/react/Button';
+import Select from '@mezzanine-ui/react/Select';
+```
+
+Named exports from the barrel (hooks, types, utilities):
+```ts
+import { usePagination, useCheckboxControlValue, cx } from '@mezzanine-ui/react';
+import type { ButtonProps, ButtonVariant } from '@mezzanine-ui/react';
+```
+
+Sub-path imports for component groups and core types:
+```ts
+// Navigation sub-components
+import {
+  NavigationFooter,
+  NavigationHeader,
+  NavigationOption,
+  NavigationIconButton,
+  NavigationUserMenu,
+} from '@mezzanine-ui/react/Navigation';
+
+// ContentHeader (page-level header with back button + action slots)
+import ContentHeader from '@mezzanine-ui/react/ContentHeader';
+
+// Form layout tokens from core (used with FormField)
+import {
+  ControlFieldSlotLayout,
+  FormFieldLayout,
+  FormFieldLabelSpacing,
+} from '@mezzanine-ui/core/form';
+```
+
+Spacing helpers in SCSS (from `@mezzanine-ui/system/spacing`):
+```scss
+@use '@mezzanine-ui/system/spacing';
+
+.host {
+  padding: spacing.semantic-variable(padding, vertical, spacious)
+    spacing.semantic-variable(padding, horizontal, comfort-fixed);
+  row-gap: spacing.semantic-variable(gap, calm);
+}
+```
+
+Required styles — create a `main.scss` and import it at your app entry point. All component styles are loaded at once via `@include mzn-core.styles()`:
+```scss
+@use '@mezzanine-ui/system' as mzn-system;
+@use '@mezzanine-ui/core' as mzn-core;
+
+:root {
+  @include mzn-system.common-variables('default');
+  @include mzn-system.colors();
+}
+
+/* Optional: light/dark palette theming */
+:root { @include mzn-system.palette-variables(light); }
+[data-theme='dark'] { @include mzn-system.palette-variables(dark); }
+
+/* Optional: compact density */
+[data-density='compact'] { @include mzn-system.common-variables(compact); }
+
+@include mzn-core.styles();
+```
+
+> **Note:** The `~` prefix (e.g. `~@mezzanine-ui/core`) was required by older webpack 4 + sass-loader setups. Modern tooling (Next.js 13+, Vite) resolves node_modules without it — use bare paths as shown above.
+
+## Component Categories
+
+- **General** — Button, ButtonGroup, Cropper, Icon, Layout, Separator, Typography
+- **Navigation** — Breadcrumb, Drawer, Navigation (+ sub-components), PageHeader, PageFooter, Stepper, Tab
+- **Data Display** — Accordion, Badge, Cards (BaseCard, FourThumbnailCard, SingleThumbnailCard, QuickActionCard), Description, Empty, Pagination, Table, Tag, Tooltip
+- **Data Entry** — AutoComplete, Checkbox, DatePicker, DateRangePicker, DateTimePicker, FilterArea, FormField, Input, Radio, Select, Slider, Toggle, Textarea, TimePicker, Upload, Cascader
+- **Feedback** — InlineMessage, Message, Modal, NotificationCenter, Progress, ResultState, Skeleton, Spin
+- **Others** — AlertBanner, Anchor, Backdrop, FloatingButton
+- **Utility** — Calendar, Dropdown, Popper, Portal, TimePanel, Transition animations (Collapse, Fade, Rotate, Scale, Slide, Translate)
+
+## Key Design Patterns
+
+**Polymorphic `component` prop** — most components accept a `component` prop to override the rendered HTML element or pass a router link component:
+```tsx
+<Button component="a" href="/page">Link Button</Button>
+```
+
+**Controlled/uncontrolled with control hooks** — pair components with their corresponding hook:
+```tsx
+const [value, onChange] = useCheckboxControlValue({ defaultValue: [] });
+<CheckboxGroup value={value} onChange={onChange} options={options} />
+```
+
+Available control hooks: `useAutoCompleteValueControl`, `useCheckboxControlValue`, `useInputControlValue`, `useInputWithClearControlValue`, `useRadioControlValue`, `useSelectValueControl`, `useSwitchControlValue`, `useCustomControlValue`.
+
+**Portal-based overlays** — Modal, Drawer, and Tooltip render outside the component tree via `Portal`. Use the `container` prop to target a specific DOM node.
+
+**Calendar adapter pattern** — Calendar components require wrapping the app with a date-adapter provider. Import from the library-specific entry point to avoid bundling unused date libraries:
+```tsx
+// Day.js (recommended)
+import { CalendarConfigProviderDayjs, CalendarLocale } from '@mezzanine-ui/react/dayjs';
+<CalendarConfigProviderDayjs locale={CalendarLocale.ZH_TW}>{children}</CalendarConfigProviderDayjs>
+
+// Moment.js
+import { CalendarConfigProviderMoment, CalendarLocale } from '@mezzanine-ui/react/moment';
+
+// Luxon
+import { CalendarConfigProviderLuxon, CalendarLocale } from '@mezzanine-ui/react/luxon';
+```
+
+**forwardRef** — all components forward their ref to the underlying DOM element.
+
+**React Hook Form integration** — the recommended pattern is a `BaseField` wrapper that combines `FormField` with RHF's `formState.errors` for automatic error display. `ControlFieldSlotLayout.SUB` aligns the hint/error message with the input:
+```tsx
+import { useFormContext, get } from 'react-hook-form';
+import FormField from '@mezzanine-ui/react/Form/FormField';
+import { ControlFieldSlotLayout, FormFieldLayout } from '@mezzanine-ui/core/form';
+
+function BaseField({ name, label, required, disabled, children }) {
+  const { formState } = useFormContext();
+  const error = get(formState.errors, name);
+  return (
+    <FormField
+      name={name}
+      label={label}
+      required={required}
+      disabled={disabled}
+      layout={FormFieldLayout.VERTICAL}
+      controlFieldSlotLayout={ControlFieldSlotLayout.SUB}
+      hintText={error?.message ?? ''}
+      severity={error ? 'error' : 'info'}
+    >
+      {children}
+    </FormField>
+  );
+}
+```
+
+**Message imperative API** — `Message` is a global singleton for toast notifications. Call it imperatively without rendering any JSX:
+```tsx
+import { Message } from '@mezzanine-ui/react';
+
+Message.success('儲存成功');
+Message.warning('請確認輸入資料');
+Message.error('操作失敗，請稍後再試');
+```
+
+**Select inside Modal** — when rendering a `Select` (or `AutoComplete`) inside a `Modal` or `Drawer`, pass `dropdownZIndex` higher than the overlay (default modal z-index is ~1000):
+```tsx
+<Select options={options} dropdownZIndex={1004} />
+```
+
+## Common Pitfalls for AI Assistants
+
+**Typography `variant` is not h1–h6.** The prop is named `variant` but its type is `TypographySemanticType` — a design-system semantic scale, not HTML heading levels. Valid values are `h1`, `h2`, `h3` (no h4/h5/h6), then `body`, `body-highlight`, `body-mono`, `caption`, `caption-highlight`, `annotation`, `annotation-highlight`, `button`, `input`, `label-primary`, `label-secondary`, and a few others. Never use `h4`, `h5`, or `h6`.
+```tsx
+<Typography variant="h1">Title</Typography>      // ✅
+<Typography variant="body">Body text</Typography> // ✅
+<Typography variant="h5">Subtitle</Typography>    // ❌ h5 does not exist
+```
+
+**Button icons use `icon` + `iconType`, not `prefix`/`suffix` JSX.** Pass an icon definition object (from `@mezzanine-ui/icons`) to the `icon` prop and set position via `iconType`: `"leading"` | `"trailing"` | `"icon-only"`. Do not wrap `<Icon />` in `prefix` or `suffix` props — those props do not exist on Button.
+```tsx
+import { PlusIcon } from '@mezzanine-ui/icons';
+<Button icon={PlusIcon} iconType="leading">新增</Button>   // ✅
+<Button prefix={<Icon icon={PlusIcon} />}>新增</Button>    // ❌ prefix does not exist
+```
+
+**`TextField` is a low-level layout container, not a full form field.** It renders the border/background/affix shell around an `<input>` but does not include a label, hint text, or error message. For a complete labeled form field, use `FormField` (which wraps `TextField` + `Input` + label + validation message).
+```tsx
+// Full labeled form field:
+<FormField label="Email" required errorMessage={error}>
+  <TextField><Input placeholder="you@example.com" /></TextField>
+</FormField>
+```
+
+## Further Reference
+
+- Full component index with descriptions: `packages/react/COMPONENTS.md`
+- Complete prop types and JSDoc: `*.d.ts` files in the published package (or `packages/react/src/<ComponentName>/index.tsx`)
+- GitHub: https://github.com/Mezzanine-UI/mezzanine

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mezzanine-ui/react",
-  "version": "1.0.0-rc.5",
+  "version": "1.0.0-rc.7",
   "description": "React components for mezzanine-ui",
   "author": "Mezzanine",
   "repository": {
@@ -13,6 +13,7 @@
   "module": "index.js",
   "typings": "index.d.ts",
   "sideEffects": false,
+  "llms": "./llms.txt",
   "publishConfig": {
     "access": "public"
   },
@@ -31,9 +32,9 @@
     "@floating-ui/dom": "^1.7.4",
     "@floating-ui/react-dom": "^2.1.6",
     "@hello-pangea/dnd": "^18.0.1",
-    "@mezzanine-ui/core": "1.0.0-rc.5",
-    "@mezzanine-ui/icons": "1.0.0-rc.5",
-    "@mezzanine-ui/system": "1.0.0-rc.5",
+    "@mezzanine-ui/core": "1.0.0-rc.7",
+    "@mezzanine-ui/icons": "1.0.0-rc.7",
+    "@mezzanine-ui/system": "1.0.0-rc.7",
     "@tanstack/react-virtual": "^3.13.13",
     "@types/react-transition-group": "^4.4.12",
     "clsx": "^2.1.1",

package/Selection/SelectionGroup.d.ts

@@ -1,28 +0,0 @@
-import { ComponentProps, ReactElement } from 'react';
-import { NativeElementPropsWithoutKeyAndRef } from '../utils/jsx-types';
-import Selection, { SelectionProps } from './Selection';
-export interface SelectionGroupBaseProps extends Omit<NativeElementPropsWithoutKeyAndRef<'div'>, 'children'> {
-    /**
-     * The class name of the selection group.
-     */
-    className?: string;
-}
-export interface SelectionGroupProps extends SelectionGroupBaseProps {
-    /**
-     * The selections in the group.
-     * Only Selection components are allowed.
-     * When provided, will take priority over selections prop.
-     */
-    children?: ReactElement<ComponentProps<typeof Selection>> | ReactElement<ComponentProps<typeof Selection>>[];
-    /**
-     * The selections array.
-     * When provided, Selection components will be automatically rendered.
-     * Will be ignored if children is provided.
-     */
-    selections?: SelectionProps[];
-}
-/**
- * The react component for `mezzanine` selection group.
- */
-declare const SelectionGroup: import("react").ForwardRefExoticComponent<SelectionGroupProps & import("react").RefAttributes<HTMLDivElement>>;
-export default SelectionGroup;

package/Selection/index.d.ts

@@ -1,12 +0,0 @@
-import { PropsWithoutRef, ReactElement, RefAttributes } from 'react';
-import Selection, { SelectionProps, SelectionPropsBase } from './Selection';
-export type { SelectionDirection, SelectionType, } from '@mezzanine-ui/core/selection';
-export type { SelectionProps, SelectionPropsBase };
-/**
- * @remark
- * Add type alias here for parsable to react docgen typescript.
- */
-type GenericSelection = (props: PropsWithoutRef<SelectionProps> & RefAttributes<HTMLLabelElement>) => ReactElement<any>;
-export { Selection };
-declare const _default: GenericSelection;
-export default _default;

package/Selection/index.js

@@ -1,5 +0,0 @@
-import Selection from './Selection.js';
-
-
-
-export { Selection, Selection as default };