@dungle-scrubs/admin-ui-soft 0.0.0-stage → 0.0.0

package/GUIDE.md

@@ -0,0 +1,110 @@
+# Use Admin UI Soft in an app
+
+Admin UI Soft provides the full admin-ui root and AI/chat component set on shadcn and Base UI, styled by an original soft token set: a cool slate canvas, white cards with hairline rings, compact 13px Inter type, an indigo accent, and pill status badges. The Inter font ships self-hosted. It is published to npm as `@dungle-scrubs/admin-ui-soft`.
+
+## Install the package
+
+In any app, install the published package:
+
+```sh
+pnpm add @dungle-scrubs/admin-ui-soft
+```
+
+An app inside the Hub workspace can instead add `"@dungle-scrubs/admin-ui-soft": "workspace:*"` to its dependencies, run `pnpm install`, and build the package with `pnpm --filter @dungle-scrubs/admin-ui-soft build`.
+
+Use React 19 and Tailwind CSS 4. The root entry also requires the TanStack React Form 1, Table 9, and Virtual 3 peers. The manifest records tested versions and the optional assistant-ui peers. AI runtime components need `@assistant-ui/react` and markdown components need `@assistant-ui/react-markdown` at the manifest's supported versions. Regular AI dependencies may cause package managers to install these peers even for root-only apps; tree-shaking keeps their code out of root bundles.
+
+## Compile one CSS entry
+
+Import the root stylesheet from the app's Tailwind entry:
+
+```css
+@import "@dungle-scrubs/admin-ui-soft/styles.css";
+```
+
+For AI/chat components, add the AI stylesheet immediately after it in that same file:
+
+```css
+@import "@dungle-scrubs/admin-ui-soft/styles.css";
+@import "@dungle-scrubs/admin-ui-soft/ai.css";
+```
+
+Import this app entry once. Both package stylesheets ship as uncompiled Tailwind 4 source. One Tailwind compilation supplies root and AI utilities, registry structural styles, token aliases, and local font assets. Importing the AI stylesheet separately through JavaScript compiles it alone and misses utilities. Emitted component JavaScript contains no CSS imports.
+
+The built stylesheets scan their own built modules explicitly, including inside `node_modules`. Root scanning covers UI, icons, compositions, helpers, and motion; AI scanning covers assistant-ui, diff viewer, hooks, and AI compositions. Both entries build together as separate modules so shared React contexts have one instance.
+
+Use the soft stylesheet on pages with soft components. The original admin-ui and hub-ui stylesheets define overlapping globals and should stay on separate pages.
+
+## Use root components
+
+The root exports every core UI module, admin composition, motion component, `ThemeProvider`, `useTheme`, and `useIsMobile`. Soft layout and field conveniences remain available alongside them. The full export list is in the package's `dist/index.d.ts`.
+
+```tsx
+import { Button, Card, CardContent } from "@dungle-scrubs/admin-ui-soft";
+import type { ReactElement } from "react";
+
+export function InvoiceActions(): ReactElement {
+  return (
+    <Card>
+      <CardContent>
+        <Button variant="primary">Send invoice</Button>
+      </CardContent>
+    </Card>
+  );
+}
+```
+
+`Button` accepts primary, secondary, tertiary, and critical variants plus the original core variant and size aliases. `Badge` retains the core `render`, `variant`, and `badgeVariants` API and adds `tone`. An explicit tone determines its colors; destructive defaults to critical, and other variants default to neutral. Outline stays outlined and link stays a link treatment.
+
+`Page`, `Section`, `Stack`, `Grid`, `Link`, `Banner`, `Modal`, the `Menu*` aliases, and `Divider` are soft conveniences. Canonical `EmptyState` takes its descriptive content through `description` and offers `icon` and `action` slots.
+
+## Choose bound or standalone fields
+
+`TextField`, `SelectField`, `CheckboxField`, `SwitchField`, and `TextareaField` are the canonical context-bound form-kit components. Use them through `useAppForm`, the shared field/form contexts, and the app field components registered by the form kit. Its stories cover validation, submit errors, and pending submission.
+
+For labelled controls outside a form-kit context, use `StandaloneTextField`, `StandaloneSelectField`, `StandaloneCheckboxField`, and `StandaloneSwitchField`. Their corresponding `Standalone*Props` types are exported. Each connects its label, hint, and error to its control and preserves disabled semantics.
+
+`MoneyField`, `NumberField`, `DatePicker`, and `TextArea` remain standalone conveniences. Pass decimal strings to `MoneyField`; pass local calendar dates as `YYYY-MM-DD` strings to `DatePicker`. No UTC conversion is used.
+
+## Use the canonical DataTable
+
+`DataTable` uses TanStack Table 9. Build columns with `createDataTableColumnHelper<TRow>()` or the exported `DataTableColumnDef<TRow>` type. Pass `label`, `columns`, `rows`, and `getRowId`.
+
+Client mode sorts, searches, filters, and paginates rows locally. Server mode takes `mode="server"`, controlled `state`, `onStateChange`, and `total`. `createDataTableState` and `updateDataTableState` provide the shared state contract. Column metadata supports widths, alignment, filters, and responsive visibility. Rows virtualize within the table's scroll region.
+
+Set initial pagination through `defaultState.pagination` and offer sizes through `pageSizeOptions`. Supplying `onSelectionChange` enables selection; `selection` controls the selected IDs. Select-all affects only the visible page, and selection persists across pages. Loading, error/retry, empty states, row actions, and controlled query state follow the original admin-ui contract. The earlier simple table API has been removed. Invoice stories use this same production table.
+
+## Use the AI entry
+
+Import compositions and namespaces through `@dungle-scrubs/admin-ui-soft/ai`. For example, `AuiThread.Thread` is the classic thread, `Composer.Composer` is the presentational composer, and `ConfidenceMarker.ConfidenceMarker` is a presentational item. Namespaces avoid collisions between classic and element components. The complete list is in the package's `dist/ai.d.ts`.
+
+The entry includes the agent console, attention feed, conversation browser, run inspector, tool approval, transcript viewer, redaction marker, and usage meter. `MockRuntimeProvider`, manual clocks, and synthetic media support local stories without live services. Runtime-bound components require an assistant-ui runtime provider; presentational elements accept their documented props directly.
+
+## Set theme and density
+
+Use `ThemeProvider` or add `dark` to the document's `<html>` element. Removing it selects light mode. `ThemeProvider` retains system-theme resolution, storage, and the core keyboard toggle.
+
+Apply `data-density="comfortable"` to a container for 38px buttons and fields and 20px card padding. Defaults are 30px buttons and fields with 8px corners, and cards with 12px corners and 16px padding. Explicit button size aliases and caller sizing utilities remain supported. Use `Section` around a `Card` for an outside heading; `CardHeader` and `CardTitle` stay inside their card. shadcn's semantic variables (`--background`, `--primary`, `--muted` and the rest) map onto the soft tokens, so copied shadcn components follow the theme in both modes.
+
+## Tokens, fonts, and licenses
+
+All tokens live in the package's `dist/tokens.css`, written for this package: canvas, surface, border and text tiers; the indigo accent; info, success, warning, caution and critical tones (each with a fill, an ink, a tint and a border); a 4px space scale; a 12, 13, 15, 18 and 22px type scale with weights 420, 540, 640 and 720; radii; slate-tinted shadows; and the two densities. `.dark` redefines the palette and shadows. Override any `--soft-*` variable after the import to retheme an app.
+
+The font is Inter 4.1, the unmodified variable `woff2` from the official release, self-hosted under `dist/fonts/`. Its source URL and checksums are in `dist/fonts/inter.css`.
+
+The [third-party notices](THIRD-PARTY-NOTICES.md) cover the shadcn/ui components, Inter (SIL Open Font License 1.1) and the assistant-ui registry items. The [vendored changes](VENDORED-CHANGES.md) record source provenance and local styling changes.
+
+## Stories and checks
+
+In the Hub repository, from the workspace root:
+
+```sh
+pnpm storybook:soft
+pnpm build-storybook:soft
+pnpm exec vitest run --project unit packages/admin-ui-soft
+pnpm exec vitest run --project soft-storybook-light --project soft-storybook-dark
+pnpm lint
+pnpm typecheck
+```
+
+Storybook uses `http://127.0.0.1:17482`. Stop any other Hub Storybook before starting it because they share the registered port. Copied stories retain their hierarchy under `Admin UI Soft/`, alongside the theme and invoice examples. Both theme projects retain the accessibility error gate and shared cursor checks. The original `pnpm storybook` command opens the original kit.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kevin Frilot
+
+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

@@ -1,3 +1,37 @@
-# Temporary Holding Version
+# @dungle-scrubs/admin-ui-soft
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A soft, dense admin UI kit: the full Hub admin-ui component set (shadcn on
+Base UI, `base-mira`) restyled with its own token set. Cool slate canvas,
+white cards with hairline rings, compact 13px Inter type, an indigo accent,
+pill status badges, tidy tables, banners and empty states, in light and dark.
+
+- Install with `pnpm add @dungle-scrubs/admin-ui-soft`.
+- React 19 and Tailwind CSS 4. The stylesheet ships as uncompiled Tailwind
+  source; import it from your app's Tailwind entry:
+
+  ```css
+  @import "@dungle-scrubs/admin-ui-soft/styles.css";
+  /* only if you use the AI/chat components: */
+  @import "@dungle-scrubs/admin-ui-soft/ai.css";
+  ```
+
+- Retheme by overriding the `--soft-*` variables defined in `dist/tokens.css`.
+
+```tsx
+import { Badge, Button, Card, CardContent, Page } from "@dungle-scrubs/admin-ui-soft";
+
+<Page title="Invoices" actions={<Button>New invoice</Button>}>
+  <Card>
+    <CardContent>
+      <Badge tone="success">Paid</Badge>
+    </CardContent>
+  </Card>
+</Page>;
+```
+
+Setup, components, theming and checks are documented in
+[GUIDE.md](GUIDE.md), which ships with the package. Third-party material
+(shadcn/ui, Inter, assistant-ui) is listed in
+[THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md).
+
+MIT.

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,25 @@
+# Third-party notices
+
+This package contains material with separate licenses. The package's MIT license covers original Hub code, including the design tokens and component treatments in `src/styles/`. The material below keeps its own license.
+
+## shadcn/ui
+
+The components in `src/components/ui/` originated in shadcn/ui's Base UI `base-mira` registry and were copied through Hub's `admin-ui` scaffold. Copyright (c) 2023 shadcn. The original MIT license is in `licenses/shadcn-MIT.md`. Local changes are recorded in `VENDORED-CHANGES.md`.
+
+Source: https://github.com/shadcn-ui/ui
+
+Base UI remains an installed runtime dependency under its own MIT license.
+
+## Inter
+
+`src/styles/fonts/InterVariable.woff2` is the unmodified upright variable font from the official Inter 4.1 release, https://github.com/rsms/inter/releases/download/v4.1/Inter-4.1.zip (archive SHA-256 `9883fdd4a49d4fb66bd8177ba6625ef9a64aa45899767dde3d36aa425756b11e`, file SHA-256 `693b77d4f32ee9b8bfc995589b5fad5e99adf2832738661f5402f9978429a8e3`). `src/styles/fonts/inter.css` is a local `@font-face` rule for it.
+
+Inter is copyright (c) 2016 The Inter Project Authors, under the SIL Open Font License 1.1. The license from the release is in `licenses/Inter-OFL.txt`. The font is not covered by Hub's MIT license.
+
+Source: https://github.com/rsms/inter
+
+## assistant-ui registry
+
+`src/components/assistant-ui/`, the registry UI additions, related hooks, and registry structural CSS derive from https://r.assistant-ui.com through Hub admin-ui at ac114fc. The assistant-ui project is copyright (c) 2026 AgentbaseAI Inc., under MIT. Its license is retained in `licenses/assistant-ui-MIT.txt`. Hub compositions, stories, and fixtures retain the package MIT attribution. Inherited registry changes and local soft theme adaptations are recorded in `UPSTREAM-VENDORED-CHANGES.md` and `VENDORED-CHANGES.md`.
+
+Source: https://github.com/assistant-ui/assistant-ui