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

package/llms.txt

@@ -28,22 +28,71 @@ import Select from '@mezzanine-ui/react/Select';
 
 Named exports from the barrel (hooks, types, utilities):
 ```ts
-import { usePagination, useCheckboxControlValue } from '@mezzanine-ui/react';
+import { usePagination, useCheckboxControlValue, cx } from '@mezzanine-ui/react';
 import type { ButtonProps, ButtonVariant } from '@mezzanine-ui/react';
 ```
 
-Required CSS — import per component's style entry from @mezzanine-ui/core:
+Sub-path imports for component groups and core types:
 ```ts
-import '@mezzanine-ui/core/button/styles';
-import '@mezzanine-ui/core/select/styles';
+// 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, Switch, Textarea, TimePicker, Upload, Cascader
+- **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)
@@ -65,15 +114,85 @@ Available control hooks: `useAutoCompleteValueControl`, `useCheckboxControlValue
 
 **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 a date adapter. Install one of `dayjs >= 1`, `moment >= 2`, or `luxon >= 3` and pass it to `CalendarConfigProvider`:
+**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
-import { CalendarConfigProvider } from '@mezzanine-ui/react';
-import dayjs from 'dayjs';
-<CalendarConfigProvider methods={dayjsMethods}>...</CalendarConfigProvider>
+// 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`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mezzanine-ui/react",
-  "version": "1.0.0-rc.6",
+  "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.6",
-    "@mezzanine-ui/icons": "1.0.0-rc.6",
-    "@mezzanine-ui/system": "1.0.0-rc.6",
+    "@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",