@loykin/designkit 0.0.3 → 0.0.5

package/docs/guides/README.md

@@ -2,11 +2,15 @@
 
 The Playground's **Guides** group contains complete product flows. Existing template groups remain visual API references; they do not receive an AI guide merely because a workflow uses that template.
 
-| Workflow            | Pattern ID            | Connected destinations                 | Contract                                        |
-| ------------------- | --------------------- | -------------------------------------- | ----------------------------------------------- |
-| Resource Management | `managed-table`       | table → detail Sheet; create/edit page | [Managed Table](./managed-table.md)             |
-| Publishing          | `publishing-workflow` | blog collection → article route        | [Publishing Workflow](./publishing-workflow.md) |
-| Commerce            | `commerce-workflow`   | filtered catalog → product route       | [Commerce Workflow](./commerce-workflow.md)     |
+Read [AI UI Implementation Contract](./ai-ui-implementation-contract.md) before implementing any Guide screen — it defines the mandatory build order (template → slot → component → variant → minimal custom CSS) that every Guide below assumes.
+
+| Workflow            | Pattern ID             | Connected destinations                 | Contract                                          |
+| ------------------- | ---------------------- | -------------------------------------- | ------------------------------------------------- |
+| Resource Management | `managed-table`        | table → detail SidePanel; create/edit page | [Managed Table](./managed-table.md)               |
+| Operations          | `kubernetes-workspace` | Pod table → detail panel → tool dock   | [Kubernetes Workspace](./kubernetes-workspace.md) |
+| Forms               | `form-workflow`        | create, edit, and settings pages       | [Stacked Form](./form-workflow.md)                |
+| Publishing          | `publishing-workflow`  | blog collection → article route        | [Publishing Workflow](./publishing-workflow.md)   |
+| Commerce            | `commerce-workflow`    | filtered catalog → product route       | [Commerce Workflow](./commerce-workflow.md)       |
 
 ## How to use these guides
 

package/docs/guides/ai-ui-implementation-contract.md

@@ -0,0 +1,52 @@
+# AI UI Implementation Contract
+
+This contract applies to every Guide in `docs/guides/`. Read it once, then read the specific Guide for the workflow you are building. It exists because an executable Guide demo teaches by example — an AI session copies what the code *does* more strongly than what the prose *says*. If a Guide's TSX is full of one-off Tailwind, that reads as "styling is done ad hoc here," no matter what the Markdown claims.
+
+## Mandatory implementation order
+
+1. Select the closest executable Guide (`docs/guides/manifest.json`).
+2. Use the page template that Guide documents.
+3. Fill the template's documented slots before creating wrapper layouts.
+4. Use existing DesignKit or bundled shadcn components.
+5. Use an existing named variant for a supported visual difference.
+6. If a visual difference is reusable, add or extend a named component or variant — see `AGENTS.md`'s Implementation Priority.
+7. Use custom CSS only when the requirement is content-specific, integration-specific, and cannot be represented by an existing template, slot, component, or variant.
+
+Custom CSS is not forbidden. It must not read as the default way to build a screen.
+
+## Forbidden patterns
+
+- Reimplementing page-level layout (reading width, article typography, card elevation, section spacing) with raw `<div>` + Tailwind when a DesignKit component or variant already expresses it.
+- Overriding padding, width, typography hierarchy, or responsive behavior that a template already owns.
+- Storing Tailwind utility strings in domain/sample data (e.g. `accent: 'from-violet-500/80 ...'`). Store a semantic value (`accent: 'violet'`) and map it through a component or variant instead — an AI session should never need to invent gradient utility combinations.
+- Copying the same hand-rolled visual pattern into more than one Guide. The second occurrence is the signal to promote it to a component (see `InteractiveCard`, born from the same hover/elevation block appearing in four demos).
+
+## Classifying a `className`/`style` you're about to write
+
+- **Promote to a DesignKit template-level component** if the pattern is reusable across pages regardless of domain: reading width, article typography, metadata rows, table of contents, loading skeletons, elevation/hover behavior, cover/hero layout.
+- **Promote to a named variant** if it's a limited, enumerable visual choice on an existing component: tone, density, elevation, content width, presentation mode.
+- **Keep as local custom CSS** only when all of the following hold: it is content- or integration-specific; it cannot be expressed by an existing template, slot, component, or variant; it does not repeat in another Guide; it does not touch template-owned layout. Justify it inline:
+
+  ```tsx
+  /**
+   * Guide exception:
+   * This third-party renderer requires an explicit container height.
+   * Page spacing, typography, and responsive layout remain owned by DesignKit.
+   */
+  ```
+
+  Custom styling with no such comment should be removed or promoted the next time it's touched.
+
+## Reconstruction checklist (add to every Guide)
+
+- [ ] Existing template slots are used before custom wrapper layouts
+- [ ] Existing DesignKit or shadcn variants/components are used before custom classes
+- [ ] Reusable visual differences are implemented as named components or variants, not repeated `className` blocks
+- [ ] Custom CSS is local, minimal, and explicitly justified with a `Guide exception` comment
+- [ ] No Tailwind utility strings are stored in domain data
+- [ ] Template-owned spacing, width, typography, and responsive behavior are not overridden
+
+## Precedent
+
+- `ArticleCover`, `ArticleByline`, `ArticleToc`, `ArticleBody`, `ArticleBodySkeleton` (`@loykin/designkit`) — extracted from the Publishing guide's hand-rolled article markup; a `tone: ArticleTone` prop replaces raw gradient strings in sample data.
+- `InteractiveCard` (`@loykin/designkit`) — the hover-lift-card treatment duplicated across the Publishing, Commerce, Browse, and Blog Feed demos, promoted to one component.

package/docs/guides/commerce-workflow.md

@@ -12,6 +12,8 @@ Use this guide to build a discovery-to-decision commerce experience. The executa
 
 The existing **Browse / Catalog** and product detail template demos remain visual references. This Guide defines their behavioral connection.
 
+Read [AI UI Implementation Contract](./ai-ui-implementation-contract.md) first. Product cards use DesignKit `InteractiveCard` for the clickable, hover-lifting shell — the same component the Publishing guide uses — not a hand-rolled `<div className="... hover:shadow-md ...">`.
+
 ## Route contract
 
 ```text
@@ -45,3 +47,4 @@ Selecting a product card navigates to the product route. Browser Back and the pr
 - [ ] Product breadcrumb returns to catalog
 - [ ] Purchase action exists only on the product route
 - [ ] No nested page templates and no product Sheet
+- [ ] Product cards use `InteractiveCard`, not a hand-rolled hover/elevation `className` block

package/docs/guides/form-workflow.md

@@ -0,0 +1,202 @@
+# Stacked Form Workflow Contract for AI
+
+Use this contract for create, edit, and settings forms. It standardizes the visual structure and component boundaries. It does not prescribe a form-state, validation, routing, or data-fetching library.
+
+## Canonical reference
+
+- Pattern ID: `form-workflow`
+- Playground: **Guides / Forms / Stacked Form**
+- Page template: `DataBodyTemplate`
+- Section primitive: `DataBodyTemplate.Group layout="stacked"`
+
+The existing **DataBodyTemplate / Form / Horizontal**, **Stacked**, and **Inline** entries are visual API references. When generating a product form, follow this guide instead of selecting among those demos.
+
+Read [AI UI Implementation Contract](./ai-ui-implementation-contract.md) first.
+
+The executable Playground example uses React Hook Form to demonstrate shared state across modular section components, controlled DesignKit inputs, and field-level errors. React Hook Form is a Playground implementation choice, not a DesignKit dependency or part of this visual contract.
+
+## Non-negotiable visual contract
+
+1. Render the form as a full route page by default. Do not use a Sheet for ordinary create, edit, or settings work.
+2. Keep the route hierarchy in `PageTopBar`: for example, `Resources / Members / Add member`.
+3. Use one `DataBodyTemplate` page root.
+4. Use the stacked form shape for create, edit, and settings pages. Do not switch to `horizontal` or `inline` because the domain changed.
+5. Divide the form into one or more `DataBodyTemplate.Group layout="stacked"` sections according to meaning, not visual preference.
+6. Wrap each field in `FormField` (label, control, and `error`/`helperText`) instead of hand-rolling a `space-y-1.5` + `Label` block; keep the fields inside a group at `space-y-3`.
+7. Use DesignKit controls and the established compact control sizing: `h-8 text-sm` for inputs and selects.
+8. End the form in `FormActions` (`status`, `submitLabel`, `onCancel`) instead of hand-rolling the bottom action row — it already puts Cancel before the right-aligned primary submit action and renders the divider above it. Do not add a second divider around it.
+9. Pass validation text to `FormField`'s `error` prop; pass form-level failure to `FormActions`' `status` prop, inside the same form boundary.
+10. A submitting, refreshing, or validation state must not replace or flash the page header or unrelated groups.
+
+## Module boundary contract
+
+Treat each semantic group like tab-scoped content: implement it as a named component instead of one large page function.
+
+- The route component owns only `DataBodyTemplate`, breadcrumb, title, and route-level description.
+- A form component owns the submit boundary and bottom actions.
+- Each section component returns one stacked `DataBodyTemplate.Group`.
+- Section-only state and asynchronous work stay in that section component when possible.
+- Shared form state may be provided by the form component through props, context, React Hook Form, or another application-selected mechanism.
+- Do not lift section-only pending, error, or refresh state into the page header.
+- Do not nest another page-level template inside the form or a Group.
+
+Separating components is a behavior boundary, not permission to change their layout. Every section still uses the same stacked Group contract.
+
+## Save boundaries
+
+The visual system remains the same; only form ownership changes.
+
+| Workflow                                     | Form ownership                           | Actions                                                         |
+| -------------------------------------------- | ---------------------------------------- | --------------------------------------------------------------- |
+| Create or edit one record                    | One form owns all stacked sections       | One bottom action row after the final section                   |
+| Settings saved as one document               | One form owns all stacked sections       | One bottom action row after the final section                   |
+| Settings with independently saved categories | Each section component owns its own form | Each stacked section ends with its own right-aligned action row |
+
+Do not create separate forms merely because the screen contains multiple Groups. Split forms only when the server-side save boundaries are genuinely independent.
+
+## Canonical composition
+
+The following is the concrete React Hook Form composition used by the Playground. Applications may replace React Hook Form, but must preserve the same component and visual boundaries.
+
+```tsx
+import { Controller, FormProvider, useForm, useFormContext } from 'react-hook-form'
+
+interface MemberFormValues {
+  name: string
+  email: string
+  role: string
+  active: boolean
+}
+
+function IdentitySection() {
+  const {
+    register,
+    formState: { errors },
+  } = useFormContext<MemberFormValues>()
+
+  return (
+    <DataBodyTemplate.Group
+      layout="stacked"
+      title="Identity"
+      description="Basic account information."
+    >
+      <div className="space-y-3">
+        <FormField label="Name" htmlFor="member-name" error={errors.name?.message}>
+          <Input
+            id="member-name"
+            {...register('name', { required: 'Enter a member name.' })}
+            aria-invalid={Boolean(errors.name)}
+            className="h-8 text-sm"
+          />
+        </FormField>
+      </div>
+    </DataBodyTemplate.Group>
+  )
+}
+
+function AccessSection() {
+  const { control } = useFormContext<MemberFormValues>()
+
+  return (
+    <DataBodyTemplate.Group
+      layout="stacked"
+      title="Role & access"
+      description="Default workspace permissions."
+    >
+      <div className="space-y-3">
+        <FormField label="Role" htmlFor="member-role">
+          <Controller
+            control={control}
+            name="role"
+            render={({ field }) => (
+              <Select value={field.value} onValueChange={field.onChange}>
+                <SelectTrigger id="member-role" className="h-8 text-sm">
+                  <SelectValue />
+                </SelectTrigger>
+                <SelectContent>{/* roles */}</SelectContent>
+              </Select>
+            )}
+          />
+        </FormField>
+        <Controller
+          control={control}
+          name="active"
+          render={({ field }) => <Switch checked={field.value} onCheckedChange={field.onChange} />}
+        />
+      </div>
+    </DataBodyTemplate.Group>
+  )
+}
+
+function MemberForm() {
+  const form = useForm<MemberFormValues>({
+    defaultValues: {
+      name: '',
+      email: '',
+      role: 'viewer',
+      active: true,
+    },
+  })
+
+  const submitMember = (values: MemberFormValues) => {
+    // Application-owned mutation or submit behavior.
+  }
+
+  return (
+    <FormProvider {...form}>
+      <form className="contents" onSubmit={form.handleSubmit(submitMember)}>
+        <IdentitySection />
+        <AccessSection />
+        <FormActions submitLabel="Save" />
+      </form>
+    </FormProvider>
+  )
+}
+
+export function MemberCreatePage() {
+  return (
+    <DataBodyTemplate
+      topBar={<PageTopBar left="Resources / Members / Add member" />}
+      title="Add member"
+      description="Create a workspace member."
+    >
+      <MemberForm />
+    </DataBodyTemplate>
+  )
+}
+```
+
+React Hook Form is used here to prove that independently implemented Group components can share one form boundary. It remains a Playground-only dependency. Replacing it with ordinary React state, Formik, or another form tool must not change the rendered structure.
+
+## Settings with independent saves
+
+When settings categories save independently, retain the same stacked appearance and move each form boundary into its section component.
+
+```tsx
+function ProfileSettingsSection() {
+  return (
+    <DataBodyTemplate.Group layout="stacked" title="Profile">
+      <form className="space-y-3" onSubmit={saveProfile}>
+        {/* profile fields */}
+        <div className="flex justify-end">
+          <Button type="submit" size="sm" className="h-8 text-xs">
+            Save profile
+          </Button>
+        </div>
+      </form>
+    </DataBodyTemplate.Group>
+  )
+}
+```
+
+## Review checklist
+
+- Create, edit, and settings screens all use the stacked shape.
+- The page is a route rather than a Sheet unless the task explicitly requires a constrained secondary edit.
+- Breadcrumb, title, Groups, fields, and actions follow the same vertical order.
+- Groups are named components and unrelated section state is not owned by the route header.
+- Group count follows the information model; it does not select a different layout.
+- Form and validation libraries remain application choices.
+- Bottom actions belong to the form that they submit.
+- Fields use `FormField`, not a hand-rolled `space-y-1.5` + `Label` block.
+- The bottom action row uses `FormActions`, not a hand-rolled Cancel/submit `div`.

package/docs/guides/kubernetes-workspace.md

@@ -0,0 +1,169 @@
+# Kubernetes Workspace Contract for AI
+
+Use this contract for operational resource browsers where people repeatedly inspect a collection, compare resource state, and open logs or a shell without losing list context.
+
+The executable reference is available at:
+
+- `/sidebar/kubernetes-workspace-guide`
+- `/header/kubernetes-workspace-guide`
+
+The `DataBodyTemplate / Kubernetes` entry is a visual API reference backed by the same composition. The **Guides / Operations / Kubernetes Workspace** entry is the normative workflow contract.
+
+Read [AI UI Implementation Contract](./ai-ui-implementation-contract.md) first.
+
+## 1. Workflow identity
+
+This is one workspace with three distinct interaction layers:
+
+1. The resource table owns discovery, search, filters, refresh, sorting, and selection context.
+2. A right SidePanel owns concise inspection of the selected resource.
+3. A bottom Control Dock owns persistent work such as logs, shell sessions, and cluster events.
+
+Do not flatten these concerns into one table component. Keep query state, selected-resource inspection, and long-running tools independently replaceable.
+
+## 2. Required composition
+
+- Use one `DataBodyTemplate` as the only page-level template.
+- Put GridKit `GlobalSearch` and a BaseKit `FilterInput` (`type: 'select'`, keyed to the namespace column) in the DataGrid header slots. GridKit's own `SelectFilter`/`MultiSelectFilter` do not expose a `size`/`className` prop, so they cannot be sized to match `GlobalSearch`; `FilterInput` can.
+- Use BaseKit `SidePanelProvider` with DesignKit `PanelTemplate` for row inspection. Put `Shell`/`Logs` (and any other panel-opening actions) in `PanelTemplate`'s `actions` slot next to the title, not in `footer` — footer is for closing/committing the panel, not for opening other tools. Render `Close` as a plain icon button (no confirmation) since dismissing a read-only inspection panel is not a destructive action.
+- Use BaseKit `ControlBarProvider` as the tab and persistence model for the bottom dock.
+- Keep Kubernetes API clients, authorization, watches, and mutations in the consuming application.
+- Keep GridKit, `FilterInput`, SidePanel, and Control Bar as application or Playground integrations; they are not DesignKit runtime dependencies.
+
+## 3. Resource collection boundary
+
+Create a named resource component such as `PodsResource`. It owns:
+
+- collection query parameters and result rendering;
+- search and filter state;
+- column definitions and row actions;
+- opening the selected resource in the SidePanel;
+- opening resource tools in the Control Dock.
+
+The route or workspace component owns only cluster context, page hierarchy, providers, and layout. It must not absorb every table and panel implementation detail.
+
+For server-backed data, put search, namespace, sorting, pagination or cursor, and refresh inputs into one query model. Preserve the previous successful result during background refresh when possible. Show initial loading, empty, filtered-empty, permission failure, and refresh failure as distinct states.
+
+## 4. Row interaction contract
+
+Clicking a Pod row opens a read-oriented detail SidePanel. It must not implicitly open logs or start a shell.
+
+The detail panel should show enough information to decide the next action:
+
+- status, readiness, restarts, and age;
+- node, owner/controller, and QoS class;
+- namespace and stable resource name;
+- explicit `Logs` and `Shell` actions.
+
+Use a full detail route only when the resource has deep navigation, editable configuration, history, or a stable URL that users must share. Use the SidePanel for quick inspection that should preserve table position and filters.
+
+Row-level Logs and Shell icon buttons may remain for expert access. They must stop row-click propagation and have accessible names.
+
+## 5. Control Dock contract
+
+Logs, shell sessions, and cluster events are persistent workspace tools, not transient popovers.
+
+- Keep the dock visible at the bottom even with zero tabs.
+- The empty dock is 36px tall and communicates `No active resource panels`.
+- Opening a tool expands the dock to its working height.
+- The dock participates in the workspace flex layout. It must reduce the table region rather than overlap or cover rows.
+- Closing the last tab returns to the empty dock; it does not remove the dock.
+- Deduplicate tools by tool type and resource identity. Reopening an existing Logs or Shell tool activates its tab.
+- Collapsing preserves tabs and active state.
+- Events are cluster-scoped; Logs and Shell are resource-scoped.
+
+The Control Bar package supplies both the tab model (`useControlBar`) and the tab strip chrome (`ControlBar`) — render `<ControlBar />` for the dock header and content instead of hand-building a tab strip. The application still owns domain-specific tool renderers (via `registerTabType`) and any dock action beyond the package's own collapse/expand/fullscreen controls (e.g. an "Events" trigger).
+
+Pass `alwaysVisible` and `emptyState` so the dock stays mounted at zero tabs instead of unmounting: `<ControlBar alwaysVisible emptyState="No active resource panels" />`. Do not hand-build an empty-state wrapper around `ControlBar` — the package owns this directly.
+
+## 6. Spacing and resizing
+
+- The table region must remain `min-height: 0` so it can shrink when the dock expands.
+- The SidePanel must be mounted inside the workspace provider boundary, not around the app shell.
+- The content area's bottom padding must equal its horizontal page padding. A table border touching the viewport edge reads as clipped even when it technically fits.
+- Do not add a second page shell, header, or navigation sidebar inside the demo.
+- Verify the same composition in both SidebarShell and HeaderShell.
+
+## 7. Actions and state
+
+Refresh belongs in the table header because it reloads the collection. Search and namespace filtering belong together without decorative separators that imply unrelated groups.
+
+Do not add aggregate status counters merely to fill header space. Add a summary only when it supports an operational decision and is driven by the same query scope as the table.
+
+For real clusters:
+
+- disable or hide Shell when the user lacks permission;
+- make container selection explicit for multi-container Pods;
+- stream Logs and Shell through cancellable connections;
+- announce connection, reconnecting, and terminal states;
+- clean up watches and streams when their dock tab closes;
+- avoid persisting credentials or log contents in local storage.
+
+## 8. Reference shape
+
+```tsx
+function PodsResource() {
+  const controlBar = useControlBar()
+  const sidePanel = useSidePanel()
+  const query = usePodsQuery()
+
+  const inspectPod = (pod: Pod) => {
+    sidePanel.open(
+      <PodDetailPanel
+        pod={pod}
+        onOpenLogs={() => openPodTool(controlBar, 'logs', pod)}
+        onOpenShell={() => openPodTool(controlBar, 'shell', pod)}
+      />,
+      { side: 'right', size: 420, resizable: true },
+    )
+  }
+
+  return (
+    <DataGrid
+      data={query.data}
+      columns={columns}
+      onRowClick={inspectPod}
+      headerLeft={(table) => (
+        <>
+          <GlobalSearch table={table} />
+          <FilterInput
+            config={namespaceFilterConfig}
+            value={(table.getColumn('namespace')?.getFilterValue() as string) ?? null}
+            onChange={(next) => table.getColumn('namespace')?.setFilterValue(next ?? undefined)}
+          />
+        </>
+      )}
+    />
+  )
+}
+
+function KubernetesWorkspace() {
+  return (
+    <ControlBarProvider persistKey="kubernetes-workspace">
+      <SidePanelProvider className="h-full min-h-0">
+        <div className="flex h-full min-h-0 flex-col overflow-hidden">
+          <DataBodyTemplate>{/* PodsResource */}</DataBodyTemplate>
+          <ControlBar alwaysVisible emptyState="No active resource panels" />
+        </div>
+      </SidePanelProvider>
+    </ControlBarProvider>
+  )
+}
+```
+
+## 9. Review checklist
+
+- [ ] There is exactly one page-level template and one app shell.
+- [ ] Search is GridKit `GlobalSearch` and the namespace control is a BaseKit `FilterInput`, both in the table header.
+- [ ] `GlobalSearch`, `FilterInput`, and any header `Button`s render at the same height and corner radius — verify computed style, not just class names, since GridKit/BaseKit and DesignKit resolve `--radius` independently.
+- [ ] Row click opens a Pod detail SidePanel.
+- [ ] Logs and Shell are explicit actions, not implicit row-click behavior.
+- [ ] Logs, Shell, and any other panel-opening actions live in `PanelTemplate`'s `actions` slot next to the title; `footer` is reserved for closing/committing, and `Close` is a plain icon button, not a confirmation.
+- [ ] Row action buttons stop propagation and have accessible names.
+- [ ] Detail, collection query, and dock tools have separate component/state boundaries.
+- [ ] Tool tabs deduplicate by type and resource identity.
+- [ ] The empty Control Dock remains visible after the final tab closes.
+- [ ] Expanding the dock reflows the table and never overlays it.
+- [ ] Bottom content padding equals horizontal content padding.
+- [ ] Loading, empty, permission, refresh failure, and stream failure states are defined.
+- [ ] The SidebarShell and HeaderShell routes both show exactly one navigation shell.