@momoi-labs/kiso 0.6.0 → 0.7.0

package/kiso/docs/components/README.md

@@ -40,7 +40,7 @@ behavioral reference where one exists.
 
 ## Navigation and structure
 
-- [AppShell](app-shell.md): Places Sidebar navigation beside the main application content.
+- [AppShell / ApplicationShell](app-shell.md): Provides low-level columns or the complete shared application frame.
 - [BrandMark](brand-mark.md): Decorative letter or icon beside a product name.
 - [Breadcrumb](breadcrumb.md): Shows the current location within a hierarchy.
 - [Header](header.md): Composes persistent application navigation and global actions.
@@ -62,6 +62,7 @@ behavioral reference where one exists.
 ## Required compositions
 
 - [FormField](form-field.md) composes [Label](label.md) + [Input](input.md) (or another form control) + [HelperText](helper-text.md) + [ValidationMessage](validation-message.md).
+- [ApplicationShell](app-shell.md) composes [Sidebar](sidebar.md) + [Navigation](navigation.md) + [Header](header.md) + page content.
 - [Header](header.md) composes [Link](link.md) + [IconButton](icon-button.md) + optional [DropdownMenu](dropdown-menu.md).
 - [Table / DataTable](table.md) composes [EmptyState](empty-state.md), [Skeleton](skeleton.md), and [Pagination](pagination.md) for empty, loading, and paged states.
 - [PageHeader](page-header.md) composes a title + optional subtitle + [Buttons](button.md).

package/kiso/docs/components/app-shell.md

@@ -4,6 +4,8 @@
 
 AppShell places persistent [Sidebar](sidebar.md) navigation beside the main
 application content. It owns the page columns, not navigation state.
+ApplicationShell composes the standard Sidebar, Navigation, Header, and main
+column when a product wants the complete frame.
 
 ## Anatomy
 
@@ -19,6 +21,36 @@ The two slots are direct children. AppShell is a `div`; AppShellMain is a
 `main` with `min-width: 0`, so wide tables and log lines cannot push the
 Sidebar off screen. Sidebar owns its header, body, and footer.
 
+ApplicationShell takes `brand`, optional `primaryAction`, navigation groups,
+optional `footer`, optional `header`, and page content. A destination contains
+`href`, `label`, optional `active`, optional `onClick`, and optional leading or
+trailing content. The caller still decides the current destination and whether
+a destination follows its link or changes a view in place.
+
+```tsx
+<ApplicationShell
+  brand={<ProductBrand />}
+  navigation={[{
+    label: "Applications",
+    destinations: apps.map((app) => ({
+      href: `#app-${app.id}`,
+      label: app.name,
+      active: app.id === currentId,
+      onClick: () => open(app.id),
+    })),
+  }]}
+  header={<CurrentLocation />}
+  footer={<ProductSettings />}
+>
+  {page}
+</ApplicationShell>
+```
+
+When `onClick` is present, ApplicationShell prevents link navigation and calls
+it. Without `onClick`, the destination remains a normal link. Use
+`navigationLabel` to distinguish this navigation landmark when the default
+`Primary` label is not specific enough.
+
 ## Variants
 
 One layout. No variant prop. Compose [Header](header.md) and
@@ -55,6 +87,8 @@ retain their own keyboard behavior.
 
 - An application with persistent navigation beside a changing page.
 - A console containing tables, detail panes, and logs in its main column.
+- Use ApplicationShell when the product follows the standard complete frame.
+- Use AppShell directly when its Sidebar or Header composition differs.
 
 ## When NOT to use
 

package/kiso/docs/components/form-field.md

@@ -22,6 +22,28 @@ For the issue's foundational chain, read this literally as **Label + Input +
 HelperText + ValidationMessage**. FormField owns layout and ID wiring; each
 child retains its own behavior.
 
+In React, omit `children` to render the default Input. Pass one control as
+`children` to use a Textarea, Select trigger, or product-specific control.
+FormField gives that control its `id`, `aria-describedby`, and
+`aria-invalid` props. The control must forward them to its interactive DOM
+element.
+
+```tsx
+<FormField
+  id="compose"
+  label="Compose file"
+  hint="Docker Compose YAML."
+  error={errors.compose}
+>
+  <Textarea rows={12} />
+</FormField>
+```
+
+`hint` and `error` accept React content. FormField renders the error as a
+ValidationMessage and points the control at every supplied description. Use
+`fieldClassName` when the field wrapper needs a layout class; `className`
+continues to style the default Input.
+
 ```text
 Label
 Input

package/kiso/docs/components/toast.md

@@ -59,6 +59,31 @@ appearing Toast. `F8` may move focus to the Toast viewport (Radix convention);
 the timer on hover, focus, and page blur. Never make Toast the only copy of an
 essential error, completed record, or required recovery step.
 
+## React interface
+
+Wrap the application in `Toasts`, then call `useToast` from any descendant.
+The manager owns the list, IDs, six-second default duration, announcement
+urgency, dismissal, and viewport.
+
+```tsx
+function SaveButton() {
+  const notify = useToast();
+  return (
+    <Button onClick={() => notify("success", "Changes saved")}>Save</Button>
+  );
+}
+
+<Toasts>
+  <Application />
+</Toasts>
+```
+
+`notify` accepts a variant, title, and optional body. A string body renders as
+ToastDescription. A React node renders as supplied so a product can compose
+details it owns. Variants are `neutral`, `success`, `warning`, and `error`.
+The lower-level ToastProvider, ToastViewport, Toast, and Toast parts remain
+available for a controlled toast.
+
 ## When to use
 
 - Brief confirmation of a completed, non-blocking action.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@momoi-labs/kiso",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Kiso design-system contracts and generated design tokens",
   "license": "MIT",
   "repository": {