themelia-react-ui 2.0.5 → 3.0.0

package/CHANGELOG.md

@@ -1,5 +1,331 @@
 # Changelog
 
+## 3.0.0 — 2026-11-11
+
+A quality pass across base, primitives, layouts, blocks and features, and the
+removal of the deprecated and legacy API that 2.x kept for compatibility.
+Everything removed or changed is listed under "Breaking changes" and
+"Changed behaviour"; MIGRATION.md has the replacement for each removal.
+Finding-level evidence is in
+`docs/verification/2026-11-11-quality-pass-*.md`.
+
+### Breaking changes
+
+- **Chart blocks moved.** `Metric`, `MetricBar`, `MetricGrid`,
+  `MetricMicroGrid`, `MetricGradient`, `MetricSparkline` and `ChartCard` (with
+  their types) are now imported from `themelia-react-ui/blocks/analytics/charts`.
+  `themelia-react-ui/blocks/analytics` no longer loads the optional `recharts`
+  peer. See "Chart blocks moved" in MIGRATION.md.
+- **Variant props no longer accept `null`.** Affects `variant`, `size`, `tone`
+  and `align` on Alert, EmptyMedia, SidebarMenuButton, SidebarTrigger,
+  TabsList, Toggle, ToggleGroup, InputGroupAddon, InputGroupButton, Item and
+  ItemMedia. Pass `undefined` or omit the prop.
+- **Cascader and Accordion value types are narrower.** Cascader is typed by
+  mode: single takes `string | null`, `multiple` takes and emits string
+  arrays (`CascaderSingleProps`, `CascaderMultipleProps`). `Accordion` is
+  generic over its value type instead of `any[]`.
+- **Removed.** The deprecated and legacy API is gone: second names for one
+  component, re-exports from old paths, props and string keys that had no
+  effect, the `asChild` composition form (use `render`), and props that
+  duplicated another prop (a label beside a `strings` key, a flat prop beside
+  a `slots` key, a boolean beside the option that implies it). The entries
+  `themelia-react-ui/features/sync` and `themelia-react-ui/base/sheet` no
+  longer exist. Every removal and its replacement is listed in "Upgrading
+  from 2.x to 3.0" in MIGRATION.md.
+
+### Changed behaviour
+
+Review these when upgrading.
+
+- **Fabricated defaults removed.** InvoiceLineItems shows no tax unless
+  `taxRate` is passed (it was 20%). LoyaltyPoints shows no tier chip unless one
+  is supplied. SubscriptionSummaryCard's status chip is neutral unless
+  `statusTone` is set. SeoListingCard renders no link without `baseUrl`.
+- **Value primitives.** Date, Time, DateTime and RelativeTime render
+  `<time dateTime>` instead of `<span>`. Number, Percent, Money and Dimensions
+  read grouped strings in full (`"1,234.5"`); a string with trailing text
+  renders the empty label instead of a truncated number. Values that round to
+  zero print without a minus. Currency codes are upper-cased. A same-day
+  DateRange collapses to one date. FileSize prints `1 MB`, not `1,024 KB`.
+  `<Initials value={null}>` renders nothing. A bad date-fns pattern renders the
+  empty label instead of throwing. `mailto:` values are percent-encoded,
+  `host:port` URLs get `https://`, and protocol-relative URLs open externally.
+- **Button.** Toggling `loading` keeps the same element, so focus is retained.
+- **Combobox family.** Selected chips use the neutral fill with the accent
+  highlight (was primary). Results from the previous query are withheld as soon
+  as the query changes. Creating an option no longer reports a selection
+  change. Suggestions debounce defaults to 300 ms (was 250).
+- **Tables.** Pagination links carry real hrefs. Single-select tables have no
+  select-all. Stored column visibility applies after mount, so server and
+  client markup match. Missing cell values show "—".
+- **Filters and DataView.** Clearing search removes the filter. MULTI_SELECT
+  offers set operators. `validation` and `maxSelected` are enforced. Date
+  filters compare calendar days. A SEARCH filter whose key names a row field
+  searches only that field.
+- **Forms.** SchemaForm ignores repeat submits and focuses the first invalid
+  field. Values of hidden conditional fields are excluded unless `hiddenValues`
+  asks for them.
+- **Search.** GlobalSearchDialog closes on result selection (`closeOnSelect`)
+  and reports one close per Escape. AsyncPreview aborts its request on close
+  unless it has a `cacheKey`, in which case the request finishes into the cache.
+- **Overlays.** ConfirmDialog calls `onCancel` on Escape.
+- **Navigation.** Current entries carry `aria-current` by default in the
+  sidebar, AsideNavShell, WorkspaceNav and the default link renderer.
+  HeaderSearch opens on ⌘K or Ctrl+K unless `shortcutModifier` is set, and not
+  while typing in a field. HeaderNotifications derives its unread count from the `read` flags,
+  names its trigger "Notifications, N unread", and "Mark all as read" is a menu
+  item. SidebarNavigation has no default "Platform" label.
+- **Layouts.** A Page inside a contained StackedLayout has no inline gutter by
+  default. WorkspaceLayout's content region is a `div` when it sits inside an
+  existing `main`. SectionNav moves focus into the section it activates.
+  BreadcrumbProgress renders unreachable steps as text.
+- **Activities.** An ActivityRow is a list item with a real button for its
+  primary action, not `role="button"`. Rows without a headline show the event
+  label.
+- **Kanban.** A clickable card without a drag handle opens with Enter and
+  drags with Space. A card with a handle uses the new `KanbanItemTrigger`.
+- **Comments and mentions.** Mention searches start when a picker opens, not on
+  mount. Submitted attachment ids are the uploader's. A draft with a failed
+  attachment is not posted.
+- **Calendars.** EventCalendar shows its view switcher when uncontrolled, its
+  legend chips toggle, and day names are long locale dates with event counts.
+- **Media library.** Gallery command names include the asset name. The default
+  `confirmEmpty` copy is "Add items".
+- **Headings.** Metric values, gift card and loyalty balances and dense-info
+  scores render as `<p>` through `Heading tag`, not as headings.
+- **Geometry.** TagsInput and Cascader lists share the 18rem cap. The
+  standalone sidebar collapses in 150 ms ease-out and honours reduced motion.
+  ProductVariantsBulkTable rows use the shared Table geometry.
+  DenseInfoProjectCard has no inset of its own. Toggle groups use logical
+  corners.
+- **DOM hooks.** Blocks and features that rendered through the removed
+  ContentBlock compose Card and keep the `content-block--component`,
+  `--header`, `--content` and `--footer` hooks and data attributes.
+- MentionChip with `onClick` and no link renders its label as a native
+  button, so the chip can be reached and activated from the keyboard. The
+  `trailing` slot stays outside that button.
+- The AiChat transcript is a named `region`, so its accessible label applies.
+
+- **Money.** `unit="minor"` uses the currency's own exponent: 1999 JPY minor
+  units print as 1,999 JPY (was 20), and KWD uses three decimals.
+- **Sidebar.** The light theme's current-entry fill is stronger. The
+  `sidebar_state` cookie is written only with `SidebarProvider stateCookie`.
+- **Selection.** MultiCombobox with `applyButton` and `closeOnSelect` commits
+  the pick that closes the list. SavedViewTabs, FilterTabs and the
+  AppointmentCalendar switchers move focus on arrow keys and apply on Enter,
+  Space or click. The product option editor refuses blank names.
+- **Tables.** `stickyFirstColumn` with row selection pins the checkbox column
+  and the first data column.
+- **Calendars.** EventCalendar month and week are an ARIA grid with one tab
+  stop and arrow, Home, End and Page keys. The `red` colour draws the warm
+  series; eight colour names map to five swatches.
+- **Media library.** Alt text and tags commit on blur or Enter. The table view
+  has table roles.
+- **Activities.** Server-rendered day groups and times no longer depend on the
+  server clock; local "Today" and relative times follow after hydration.
+- **Mentions and email.** An inline mention search continues across one space.
+  An email resolver returning an empty string falls back to the template
+  default.
+- **Blocks.** Empty cart, bookings and discount stack show an empty state.
+  AiFeedback keeps the comment until an async submit settles.
+  BookingCalendarEventCard facts are a MetadataList grid, not a `<dl>`.
+  UpcomingBooking adapts to its container.
+- **Surfaces.** Frames, region rules and anchored-list caps come from shared
+  recipes: AuthCard, MetricBar, framed InvoiceLineItems and DataViewToolbar
+  rest on `shadow-xs`, inner region rules are the quieter `/60`, and the
+  Combobox option list caps at 18rem. Product, schema-form, media-library
+  and theme-tweaker empty states use the shared wash.
+- **Spinner and QR code.** The default Spinner turns once per second and stops
+  under reduced motion. QR codes keep dark modules on a light ground in dark
+  themes.
+- **Templates.** The stacked admin template navigates with links carrying
+  `aria-current`, not tabs.
+
+- **Table edges.** The first and last columns of every table use the default
+  surface inset (24px, following `--surface-x` and `--space-scale`) instead
+  of 16px, so a table lines up with the card title, toolbar and footer around
+  it. A table inside a padded Card body sits flush with that body. DataTable
+  and DataView regions (topbar, selection bar, filter bar, footer,
+  pagination) share the same edge, and row checkboxes start on it.
+- **Calendar colours.** EventCalendar `red`, `yellow` and `green` draw their
+  own hues from the new chart series; `orange` and `amber` share one.
+
+- **AppointmentCalendar.** The feature draws one framed surface with header,
+  notice, month and agenda regions instead of two cards; pass
+  `surface="flat"` when it already sits inside a Card. Agenda rows are flush
+  rows with a time column, a category marker and a wash for conflicts; the
+  row description no longer starts with the time range. Week view lists all
+  seven days with their counts. The month and agenda panes stack by the
+  component's own width. Dismissing the double-booked notice moves focus to
+  the agenda. A controlled `date` with a new time of day no longer pulls
+  keyboard focus back. Shift+PageUp and Shift+PageDown page by year.
+
+- **Shell alignment.** StackedLayout header and subheader content shares the
+  page's measure and gutter (32px, was 24px) at every width; their inline
+  padding moved to an inner measure element. Shell headers reserve the page
+  viewport's scrollbar gutter, so chrome ends where the page content ends.
+  Shells and AuthShell render their content region as `div` when embedded
+  in an existing `main` landmark; `contentAs` still wins.
+
+- **Card.** The footer stays on the bottom edge of a card stretched to its
+  row's height. A flat Card with no `padding` inside a padded Card body takes
+  no inset of its own.
+
+- **Command search.** The search field in Command, PopoverMenu and the filter
+  editors takes the row inset, so its text lines up with the rows below it
+  whatever `--control-x` is.
+- **Control size defaults.** `--height-action` and `--height-control` default
+  to 2.125rem (were 2rem) and `--control-x` to 0.875rem (was 0.75rem), so
+  default buttons and fields are 34px tall with a 14px inline inset.
+  Set the three roots back to the old values to keep the previous sizes.
+
+### Added
+
+- **Routing.** TextLink, Link, Email, Phone and Url accept `render` for router
+  links.
+- **Dates.** Date, Time, DateTime, DateRange and `formatDateRange` accept
+  `timeZone`; UIProvider accepts `dates.timeZone`. RelativeTime accepts `now`
+  and `refreshInterval`. DateRange accepts `openStartLabel` and `openEndLabel`.
+- **Primitives and base.** FileSize `unitLabels`; Initials `emptyLabel`;
+  LanguageSwitcher `renderLabel`, `className` and `ref`; `className` on
+  KeyValueEditor, ImageUpload and DateTimeInput; `PaginationRoot`;
+  `defaultButtonLoadingStrings`; strings types and defaults for Textarea,
+  DecimalInput, DimensionsInput, CoordinatesInput, KeyValueEditor and
+  BooleanIndicator.
+- **Blocks.** `surface`, `padding` and `headerDivider` on the commerce,
+  steps and dense-info cards; `surface` on the AI blocks; `padding="none"` on
+  ChartCard and SensitiveActionCard. Metric `progressLabel`; MetricTrendChip
+  and Steps `strings`; ApiKeyList `disabled` and `pendingIds`;
+  ApiTokenManager `listStrings`; `TimelineItem.statusLabel`. CouponInputCard
+  and VoucherEntry accept `error` as text. AiConfirmation handlers may return
+  a promise.
+- **Tables and filters.** `ColumnMeta.label`; Pagination `className`;
+  `resolveDefaultOperator`, `getOperatorLabel` and `getMultiSelectOperators`;
+  `asyncConfig.resolveOptions`; `datePickerConfig.strings` and `presets`.
+- **Products and resources.** ProductVariantsManager `confirmDelete`;
+  ProductVariantsTable `storageKey={false}`; SharedResourceCard error and
+  assign strings; ResourceDetailsSection `padding="none"`.
+- **Forms and search.** SchemaForm `hiddenValues`; `getInvalidKeys()`;
+  AsyncPreview `contextKey` and hover-open triggers; GlobalSearch
+  `minQueryLength`, a function form of `slots.input` and result-count strings.
+- **Content features.** Error and retry states on MentionPicker,
+  MentionInlineSuggestions, ActivityFeed, ActivityLog and EventCalendar;
+  `useComments().pendingDeleteIds`; EmailComposer `confirmClose`; media
+  library `uploadAccept`, `maxFileSize`, `maxFiles` and `uploadRejections`;
+  `KanbanItemTrigger`; `defaultConfirmDialogStrings`.
+- **Layouts.** `useCommandShortcut` `modifier` and `allowInEditable`;
+  `skipToContentLabel` on the shells; WorkspaceLayout `mainAs`;
+  WorkspaceRecordHeader `headingTag`; SectionNav `updateHash`; PageHeader and
+  BreadcrumbProgress `strings`; StackedLayout `navLabel` and `navAs`.
+
+- **Shared seams.** `Heading tag="p" | "div" | "span"`; ActionMenu `disabled`
+  and `defaultOpen`; MetadataList `items[].span: "full"`; Empty and
+  EmptyState `surface` and `padding`; `validateFiles` and
+  `matchesFileAccept` from `base/upload`; NavigationTabs `onSelect` and
+  `items[].id`; `finalFocus` on ActionDialog, ActionDrawer and ConfirmDialog;
+  SidebarTrigger `size` and `strings`; QRCode `quietZone`.
+- **Second-pass options.** DataTable `columnVisibilityPrecedence`;
+  `FilterConfig.membershipOperators` and `datePickerConfig.locale` and
+  `shortcuts`; media-library paging (`pageSize`, `hasMore`, `loadMore`);
+  `AiConfirmation.pending`; `EmptyState.headingTag`;
+  `FulfillmentGroup.headingLevel`;
+  `SidebarNavigationRail` and `AppSidebar` search strings; formatter strings
+  across the commerce, analytics and AI blocks.
+
+- **Chart series.** `--chart-6` (red), `--chart-7` (yellow) and `--chart-8`
+  (green) in the light and dark themes, with the matching `bg-`, `text-`,
+  `border-`, `fill-`, `stroke-` and `ring-chart-*` utilities. The theme
+  editor edits and derives them. `AppointmentCategoryColor` accepts them.
+- **Card.** `CardContent` emits `data-padding`.
+
+- **AppointmentCalendar.** `surface` (`AppointmentCalendarSurface`) and
+  `locale`.
+
+- **Card.** `contentPadding` sets the body's inline inset on its own, so a
+  titled card keeps its header on the surface inset around a flush table.
+- **Sidebar parts.** `SidebarMenuSub flushEnd`, `tone="secondary"` on
+  `SidebarMenuButton` and `SidebarMenuSubButton`, `SidebarGroupLabel compact`.
+
+### Tooling
+
+- Lint enforces React hook dependencies, render purity and `jsx-a11y` rules.
+
+## 2.0.6 — 2026-11-04
+
+- AI disclosure and source controls use their visible text for accessible
+  names. Disclosure copy overrides remain available as descriptions.
+- OrderStatusCard accepts translated status labels and a formatter for the
+  displayed order reference.
+- Default layout navigation renders callback-only entries as buttons and
+  keeps disabled entries inert. Custom settings link renderers receive
+  selection through `onClick`.
+- SideNav accepts a `renderLink` adapter. Pass your app's pathname as
+  `currentPath` to preserve active-route highlighting when upgrading from
+  the implicit browser URL default.
+- AppSidebar and SidebarNavigationRail close an open drawer after app
+  navigation. Use `closeDrawerOnNavigate={false}` to keep it open.
+- Header and HeaderBreadcrumbs render in standalone and stacked layouts.
+  The built-in sidebar trigger appears only inside a sidebar provider.
+- FormField labels, hints and errors reach time, dimension, coordinate,
+  image, avatar, key/value and rich-text controls. RichTextEditor also accepts
+  `invalid` and preserves the field association in source mode.
+- A blank optional TimePicker allows native form submission.
+- AvatarUpload honors MIME types and wildcards in its file accept rules.
+- FormRichTextEditor binds React Hook Form touch, focus, invalid and disabled
+  state. Named editors include committed HTML in native submissions.
+- Combobox and MultiCombobox accept selection defaults and new value props
+  alongside their legacy bindings. All three selectors accept search and
+  open defaults.
+- WeightInput, DimensionsInput and CoordinatesInput expose direct value
+  callbacks, field blur and native form names, plus required and read-only
+  behavior.
+- TimePicker supports initial times, controlled or default popup visibility,
+  and named native values with required validation in both modes.
+- PillRadioGroup supports uncontrolled defaults and submits the selected
+  enabled option when named. Clearing still emits `null`.
+- AppointmentCalendar, Questionnaire, LanguageSwitcher and EmailComposer
+  add consistent value callbacks. TabbedResourceShell adds an initial tab.
+- Metric and MetricGrid accept a shared semantic `tone`. The legacy
+  `colorScheme` remains supported. Colored metrics keep primary progress
+  by default and accept an explicit neutral tone.
+- MediaLibrary keeps failed edits and uploads in their own panels so browsing
+  stays available. `useMediaLibrary` exposes `loadError`, `mutationError` and
+  `uploadError` alongside the existing `error` field.
+- MediaLibrary requires explicit callbacks for edits and deletes, including
+  in-memory collections and the headless mutation methods. Its Delete action
+  opens a confirmation and returns focus to the results after removal.
+- MediaLibrary keeps previous results mounted during refresh. Inline fetcher
+  and error callbacks no longer trigger reloads. Change `refreshKey` to
+  reload the current remote query explicitly.
+- MediaLibrary server pickers return selected records from earlier searches
+  and uploads. Uploads refresh the remote results and stay selected across
+  filters.
+- MediaLibrary uploads keep queued files and individual failures available
+  for the next request. Upload helpers expose the current batch's file IDs.
+- Native submissions from `Combobox`, `MultiCombobox` and
+  `AsyncResourceCombobox` now use the selected item's key, or its label
+  when no key is supplied. To keep submitting JSON objects, pass
+  `getItemValue={(item) => JSON.stringify(item)}`.
+- Async filter option freshness and retention apply within one mounted editor.
+  Chip labels are isolated to their filter provider. Applications that need
+  reuse across editor mounts can cache in their own scoped fetcher.
+- DataTable bulk-action counts include selected IDs from other server pages.
+  Use `rowSelection` for those IDs and `selectedRows` for loaded records.
+- Numeric filters use `between` and store two positional bounds, with an
+  empty string for an open end. The URL helpers still read older scalar
+  values as exact matches. Date ranges retain both calendar days on reload.
+- Inline product option editing preserves rich value labels. Options with
+  rich names can use the `onEditOption` callback for app-owned editing.
+- Money treats a single dot as a decimal separator in
+  serialized amounts, including three-decimal currencies.
+- Controlled overlays report each dismissal request through `onOpenChange`.
+  `onClose` now follows the committed visibility change.
+- RichTextEditor source edits stay in a draft until switching back to rich
+  text. The editor emits the normalized document HTML. An external value
+  change replaces the open source draft.
+- `useActivityResources` reseeds when resource values change. Equivalent
+  inline resources preserve local edits, and each mutation emits once.
+
 ## 2.0.5 — 2026-10-31
 
 - Modal scrims render again under `SidebarProvider`/`AppSidebar`. The sidebar