@mechane-ai/elements 0.8.0 → 0.10.0

package/NOTICE

@@ -30,3 +30,27 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+Bundled Sonner
+
+MIT License
+
+Copyright (c) 2023 Emil Kowalski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -41,43 +41,44 @@ export function Example() {
 Elements supplies compiled ESM, TypeScript declarations, and CSS. Ordinary React consumers need no StyleX compiler.
 Applications install their own reset and fonts. Put reset rules in the `reset` CSS layer. Elements and consumer StyleX
 rules share the compiler's ordered `priority` layers. Keep those layers at the top level: wrapping Elements in another
-layer lets consumer base declarations override component hover and focus states. Unlayered application themes can
-override token defaults.
+layer lets consumer base declarations override component hover and focus states. Packaged token defaults and themes use
+`priority1`; ordinary unlayered application rules can override the package. Consumer-generated themes follow their own
+emitted layers and selector specificity.
 
 ## Imports
 
 Every path below belongs to `@mechane-ai/elements`. There is one package, version, and stylesheet.
 
-| Entry                  | Responsibility                                                                    |
-| ---------------------- | --------------------------------------------------------------------------------- |
-| Root                   | Buttons, text, surfaces, disclosure, Avatar, and CopyValue.                       |
-| `/forms`               | Fields, inputs, selection, file picking, and settings sections.                   |
-| `/forms/dates`         | Civil-date calendars and range selection.                                         |
-| `/overlays`            | Dialog, Drawer, Menu, Popover, Preview, Tooltip, and AlertDialog.                 |
-| `/feedback`            | Async regions, skeletons, progress, meters, notices, empty states, and toasts.    |
-| `/navigation`          | Tabs, page navigation, breadcrumbs, skip links, and shortcut labels.              |
-| `/navigation/commands` | Command palette and scoped application-owned shortcuts.                           |
-| `/layout`              | Application shell, sidebar, toolbars, compound record pages, and resizable panes. |
-| `/collections`         | Tables, inspectors, collection controls, timelines, metrics, and timestamps.      |
-| `/content`             | Trace, JSON, recorded logs, and stack traces.                                     |
-| `/content/link`        | Safe content links without a renderer dependency.                                 |
-| `/content/markdown`    | Completed and streaming Markdown, embedded headings, and inert previews.          |
-| `/content/code`        | Source-preserving code highlighting.                                              |
-| `/content/diff`        | File changes and patches.                                                         |
-| `/content/tree`        | File paths, statuses, and controlled selection.                                   |
-| `/ai`                  | Conversations, messages, prompts, approvals, sources, and citations.              |
-| `/charts`              | Shared frames, legends, selection, and category types.                            |
-| `/charts/cartesian`    | Lines, areas, sparklines, small multiples, bars, and scatter plots.               |
-| `/charts/distribution` | Histograms, cumulative distributions, intervals, and ranked values.               |
-| `/charts/matrix`       | Matrices, token heatmaps, and color legends.                                      |
-| `/charts/graph`        | Supplied relationships and node selection.                                        |
-| `/charts/hierarchy`    | Treemaps.                                                                         |
-| `/charts/timeline`     | Waterfall intervals and instants.                                                 |
-| `/theme`               | Light and dark theme props.                                                       |
-| `/csp`                 | Application-supplied content security policy configuration.                       |
-| `/tokens`              | Compiled token references for runtime styles.                                     |
-| `/tokens.stylex`       | Direct definitions for StyleX authoring and themes.                               |
-| `/styles.css`          | Component styles and token defaults.                                              |
+| Entry                  | Responsibility                                                                      |
+| ---------------------- | ----------------------------------------------------------------------------------- |
+| Root                   | Buttons, text, surfaces, disclosure, avatars, and CopyValue.                        |
+| `/forms`               | Fields, inputs, selection, appearance picking, file picking, and settings sections. |
+| `/forms/dates`         | Civil-date calendars and range selection.                                           |
+| `/overlays`            | Dialog, Drawer, Menu, Popover, Preview, Tooltip, and AlertDialog.                   |
+| `/feedback`            | Async regions, skeletons, progress, meters, notices, empty states, and toasts.      |
+| `/navigation`          | Tabs, page navigation, breadcrumbs, skip links, and shortcut labels.                |
+| `/navigation/commands` | Command palette and scoped application-owned shortcuts.                             |
+| `/layout`              | Application shell, sidebar, toolbars, compound record pages, and resizable panes.   |
+| `/collections`         | Tables, inspectors, collection controls, timelines, metrics, and timestamps.        |
+| `/content`             | Trace, JSON, recorded logs, and stack traces.                                       |
+| `/content/link`        | Safe content links without a renderer dependency.                                   |
+| `/content/markdown`    | Completed and streaming Markdown, embedded headings, and inert previews.            |
+| `/content/code`        | Source-preserving code highlighting.                                                |
+| `/content/diff`        | File changes and patches.                                                           |
+| `/content/tree`        | File paths, statuses, and controlled selection.                                     |
+| `/ai`                  | Conversations, messages, prompts, approvals, sources, and citations.                |
+| `/charts`              | Shared frames, legends, selection, and category types.                              |
+| `/charts/cartesian`    | Lines, areas, sparklines, small multiples, bars, and scatter plots.                 |
+| `/charts/distribution` | Histograms, cumulative distributions, intervals, and ranked values.                 |
+| `/charts/matrix`       | Matrices, token heatmaps, and color legends.                                        |
+| `/charts/graph`        | Supplied relationships and node selection.                                          |
+| `/charts/hierarchy`    | Treemaps.                                                                           |
+| `/charts/timeline`     | Waterfall intervals and instants.                                                   |
+| `/theme`               | Light and dark theme props.                                                         |
+| `/csp`                 | Application-supplied content security policy configuration.                         |
+| `/tokens`              | Compiled token references for runtime styles.                                       |
+| `/tokens.stylex`       | Direct definitions for StyleX authoring and themes.                                 |
+| `/styles.css`          | Component styles and token defaults.                                                |
 
 Focused entries keep renderer and chart dependencies out of basic controls. There is no all-components barrel. Renderers
 initialize when used, without a consumer-managed worker pool or grammar CDN. The
@@ -94,13 +95,34 @@ Use `ToolbarAction` for page-header actions, including links composed with `rend
 `CopyValue render={<ToolbarAction />}`; the rendered control owns its appearance and CopyValue owns copy feedback. Use
 `Row` for aligned inline actions, `Stack` for related content, and `RecordPage.Content` for separated page sections.
 Detail titles wrap; list metadata truncates. Sidebar items share contiguous hit areas. Put scrolling commands with the
-navigation and reserve the divided sidebar footer for persistent account information.
+navigation and reserve the divided sidebar footer for persistent account controls. Use
+`SidebarFooter layout="navigation"` for a group of commands; its intrinsic height keeps the scrolling navigation clear.
+
+`AppShell focus` temporarily hides navigation while retaining its expansion state. `ViewStack.Panel` keeps inactive
+content mounted and measurable but removes it from keyboard and assistive-technology navigation. The application owns
+which view is active and when to unmount it; use this for a draft or reading position that must survive inspection.
+`WorkbenchScroll` requires an accessible `label`; its `flush` mode leaves list insets to the table. Its
+`scrollRestorationId` identifies the actual scroll region for application-owned restoration.
 
 `DataTable` uses 48px rows by default and truncates text to preserve stable column and virtualization geometry. Set
 `rowSizing="content"` for records that need multiline cells; virtualization then measures those rows. Long content
-belongs in a detail view or a deliberately content-sized row, not behind a clipped control. `CollectionEnd` renders
-nothing when complete unless an explicit summary is supplied. `Timeline.Root` and `Timeline.Item` compose readable
-activity with supplied titles, icons, timestamps, metadata, and body content, without interpreting domain events.
+belongs in a detail view or a deliberately content-sized row, not behind a clipped control. Use `DataTableText` for a
+primary string and optional secondary string inside one cell; both text elements own their ellipsis. Arbitrary nested
+layouts do not inherit text truncation. Give dates and numeric values sufficient column width or explicit content
+sizing. The table owns its cell insets, so an enclosing page should not add another gutter around its rows.
+`CollectionEnd` renders nothing when complete unless an explicit summary is supplied. `Timeline.Root` and
+`Timeline.Item` compose readable activity with supplied titles, icons, timestamps, metadata, and body content, without
+interpreting domain events.
+
+`Message` reserves space for secondary actions and reveals them on hover and keyboard focus; touch devices keep them
+visible. `MessageAction` supplies a named icon button and tooltip. Keep errors, decisions, and current activity outside
+that action region. `MessageBoundary` groups expandable context between messages. `PromptInput` keeps its label
+accessible while integrating the submit control into the input frame. The application owns submission identity,
+acknowledgement, and draft retention.
+
+`AgentAvatar` derives a repeatable shape and palette from a supplied seed, or renders an explicit appearance.
+`AgentAvatarPicker` accepts that appearance and reports changes; applications own storage. Keep the same seed for a
+record and store named choices rather than catalog indexes. Identity palettes remain separate from status colors.
 
 `MetricGrid layout="columns"` distributes supplied metrics by available container width. Its inline layout suits compact
 record summaries. `SettingsSection` keeps wide tables inside their scroll region; group sections with `Stack` and align
@@ -110,10 +132,10 @@ The default theme is light, with system fonts and a compact spacing scale. Impor
 `@mechane-ai/elements/theme` and spread `themeProps.light` or `themeProps.dark` onto the document root. Portaled content
 then inherits the same theme. The application owns the preference; no theme provider is required.
 
-For custom StyleX themes, import definitions from `@mechane-ai/elements/tokens.stylex`, enable CommonJS module
-resolution in the StyleX plugin, and use `stylex.createTheme`. The defining path is preserved in the archive so
-generated variables match its compiled CSS. The ordinary `/tokens` entry supplies runtime references rather than
-compile-time definitions.
+For custom StyleX themes, import definitions from `@mechane-ai/elements/tokens.stylex`, enable `useCSSLayers: true` and
+CommonJS module resolution in the StyleX plugin, and use `stylex.createTheme`. The defining path is preserved in the
+archive so generated variables match its compiled CSS. The ordinary `/tokens` entry supplies runtime references rather
+than compile-time definitions.
 
 Set the consumer compiler's `debug: false` so placement overrides use the archive's property keys. Keep definition
 resolution for compilation; bundle `/tokens` runtime references to avoid reinjecting defaults over a chosen theme.
@@ -123,6 +145,11 @@ When an application's Content Security Policy requires nonces, wrap its componen
 This is [Base UI's CSP provider](https://base-ui.com/react/utils/csp-provider); it authorizes component style tags such
 as Select's scrollbar rules. The application owns nonce generation and its security policy.
 
+Mount one `Toaster` from `/feedback` and call its exported `toast` API for notifications. Elements includes Sonner's
+structural styles in the published stylesheet, so the production package injects no additional toast style tag. Keep
+initial-read failures and field validation local; retained-content refresh failures can use one notification with Retry.
+The application owns stable notification IDs and dismissal on recovery or navigation.
+
 ## Develop and release
 
 From `workspaces/core`: