willa-workspace 0.0.3-alpha.2739b3e

package/.github/workflows/deploy.yml

@@ -0,0 +1,45 @@
+name: Deploy
+
+on:
+  push:
+    branches:
+      - master
+      - main
+
+permissions:
+  contents: write
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.27.0
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: "pnpm"
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build packages
+        run: pnpm run build:packages
+
+      - name: Build app
+        run: pnpm run build
+
+      - name: Deploy app to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./example/dist
+          keep_files: true

package/.husky/pre-commit

@@ -0,0 +1 @@
+pnpm exec lint-staged

package/AGENTS.md

@@ -0,0 +1,128 @@
+# AGENTS.md
+
+This file is the entry point for AI coding agents working in this repository.
+Read it before making changes, then follow the linked project documents for
+details.
+
+## Project Context
+
+Willa is a React component library for AI products, blogs, documentation sites,
+content platforms, MDX pages, and rich interactive content rendering.
+
+The repository is a pnpm workspace monorepo. Packages are built with `auklet`.
+
+## Document Map
+
+- [CONTRIBUTING.md](./CONTRIBUTING.md): contributor overview and common checks.
+
+- [docs/architecture.md](./docs/architecture.md): repository structure, module
+  responsibilities, dependency flow, build flow, and known pitfalls.
+
+- [docs/component.md](./docs/component.md): component creation, migration,
+  exports, example docs, and acceptance checklist.
+
+- [docs/css.md](./docs/css.md): CSS rules, theme variable ownership, cross-package
+  style dependencies, and CSS pitfalls.
+- [docs/style.md](./docs/style.md): TypeScript, React, naming, comments, and demo
+  code style.
+
+## Task Routing
+
+Read only the documents needed for the change, then follow links if the change
+crosses boundaries.
+
+- Architecture, package boundaries, build output, path aliases, or dependency
+  direction: read `docs/architecture.md`.
+- Before changing package boundaries, build config, CSS dependency config, or
+  component ownership, review the pitfalls in `docs/architecture.md`.
+- New component, component migration, exports, example docs, or public entry
+  changes: read `docs/component.md`.
+- Component CSS, theme variables, cross-package CSS dependencies, or portal
+  styling: read `docs/css.md`.
+- TypeScript, React implementation style, naming, comments, or demo code style:
+  read `docs/style.md`.
+- Contribution workflow, common checks, or commit message format: read
+  `CONTRIBUTING.md`.
+- README changes: keep README user-facing; move internal maintenance details to
+  `CONTRIBUTING.md` or `docs/`.
+
+## Working Rules
+
+- Keep package responsibilities clear. Do not make layout or content depend on
+  form, widgets, or AI.
+- Do not copy layout or content theme variables into form, widgets, or AI.
+- Do not add component theme variables to the `willa` aggregate package.
+- Do not add per-package `tsconfig.json` files; use the root `tsconfig.json`.
+- Use `auklet.config.mjs` with `defineConfig`; do not use
+  `auklet.config.ts`.
+- Keep README user-facing. Internal maintenance details belong in
+  `CONTRIBUTING.md` or `docs/`.
+- Prefer focused changes. Avoid unrelated refactors and package metadata churn
+  unless the task explicitly asks for a style or consistency pass in a defined
+  scope.
+- Do not copy the same rule into multiple documents. Prefer linking to the
+  source-of-truth document.
+- Do not include generated build output in commits unless explicitly requested.
+
+## Change Checklists
+
+For new public components:
+
+- Confirm the package choice in `docs/architecture.md` and `docs/component.md`.
+- Add package root exports and `willa` aggregate exports.
+- Add component CSS and theme variables in the owning package when needed.
+- Add or update example docs and registry entries.
+- Verify package root import, `willa` root import, single-component import, and
+  single-component CSS import.
+
+For component migrations:
+
+- Remove stale exports, component files, CSS, and theme variables from the old
+  package.
+- Move theme variables with the component's owning package.
+- Keep `willa` as an aggregate layer; do not duplicate component theme variables
+  there.
+- Update example docs, package names, imports, and CSS entries.
+
+For CSS or theme changes:
+
+- Keep structural CSS in component `index.css`.
+- Put theme values in the owning package's theme files.
+- Reuse upstream variables through declared CSS dependencies; do not copy them.
+- Check portal components have variable scope where they actually render.
+
+For documentation changes:
+
+- Keep README focused on external users.
+- Keep `CONTRIBUTING.md` as the overview and workflow entry point.
+- Put detailed rules in one focused document under `docs/`.
+- Update cross-links when renaming or moving documents.
+
+## Verification
+
+Use the narrowest check that covers the change, then broaden when shared
+behavior is affected.
+
+Common commands:
+
+```bash
+pnpm run format
+pnpm run typecheck
+pnpm run build
+```
+
+Run `pnpm run build:packages` for first-time public component additions,
+package entry changes, package migration, or build config changes. For
+example-only changes and narrow component fixes, use the smaller check that
+covers the touched behavior.
+
+For example-only changes:
+
+```bash
+pnpm dev
+pnpm run build
+```
+
+## Commits
+
+Follow the commit message format in [CONTRIBUTING.md](./CONTRIBUTING.md).

package/CONTRIBUTING.md

@@ -0,0 +1,138 @@
+# Willa Contributor Guide
+
+This document is the top-level maintenance entry point for Willa. Detailed
+architecture, component, CSS, and code style rules live in `docs/`. Read the
+relevant documents before making changes, then compare your work with the
+existing implementation patterns.
+
+## Project Scope
+
+Willa is a React component library for AI products, blogs, documentation sites,
+content platforms, MDX pages, and rich interactive content rendering.
+Components should support product-style interaction and content rendering while
+preserving single-component imports, single-component CSS imports, and
+composable theme CSS.
+
+The repository is a pnpm workspace monorepo. Packages are built with `auklet`.
+Package structure, path aliases, build outputs, and module relationships are
+documented in [Willa Architecture](./docs/architecture.md).
+
+## Guide Map
+
+Architecture, file organization, module relationships, build flow, and known
+pitfalls: [Willa Architecture](./docs/architecture.md).
+
+Component creation, migration, exports, example docs, and acceptance checks:
+[Willa Component Guide](./docs/component.md).
+
+CSS rules, theme variable ownership, cross-package variable reuse, and style
+dependencies: [Willa CSS Guide](./docs/css.md).
+
+TypeScript, React, and documentation code style:
+[Willa Style Guide](./docs/style.md).
+
+`CONTRIBUTING.md` should stay as a project-level overview. For architecture,
+component, CSS, or code style changes, treat the focused documents in `docs/`
+as the source of truth.
+
+## Pre-Submit Checks
+
+Common commands:
+
+```bash
+pnpm run format
+pnpm run typecheck
+pnpm run build
+```
+
+Run `pnpm run build:packages` when adding a first-time public component,
+changing package entries, migrating components between packages, or changing
+build configuration. For example-only changes and narrow component fixes, use
+the smaller check that covers the touched behavior.
+
+For example-only changes:
+
+```bash
+pnpm dev
+pnpm run build
+```
+
+Commits run lint-staged formatting on staged files. When adding a dependency,
+explain its purpose before installation.
+
+## Publishing
+
+Willa publishes prerelease versions to npm before stable releases. Publish from
+the workspace root so auklet can resolve all workspace packages and sort them by
+internal dependencies.
+
+Run with `--dry-run` first:
+
+```bash
+pnpm run publish:alpha -- --dry-run
+```
+
+Then publish the chosen version type with an npm 2FA code when required:
+
+```bash
+pnpm run publish:alpha -- --otp <code>
+pnpm run publish:beta -- --otp <code>
+pnpm run publish:patch -- --otp <code>
+pnpm run publish:minor -- --otp <code>
+pnpm run publish:major -- --otp <code>
+```
+
+For local token-based publishing, create `.env.local` in the workspace root:
+
+```ini
+NPM_TOKEN=<npm-token>
+```
+
+The publish scripts pass `--token env:NPM_TOKEN` to auklet, so the normal publish
+commands read the token from `.env.local`. You can still override the token value
+directly when needed:
+
+```bash
+pnpm run publish:alpha -- --token <npm-token>
+```
+
+The root `.npmrc` only declares the npm registry auth placeholder required by
+npm publish. Keep real npm tokens in `.env.local`, the shell, CI secrets, or a
+local user-level npm config.
+
+The publish scripts use auklet workspace publishing. Auklet skips private
+workspace packages, validates internal `workspace:*` dependencies, runs package
+builds, and publishes in dependency order.
+
+## Commit Messages
+
+Use conventional commit prefixes:
+
+- `feat:` for new user-facing features.
+- `fix:` for bug fixes.
+- `docs:` for documentation-only changes.
+- `chore:` for maintenance changes that do not affect runtime behavior.
+- `refactor:` for code changes that preserve behavior.
+- `test:` for test-only changes.
+
+Keep the subject concise and imperative:
+
+```text
+docs: add architecture guide
+fix: preserve theme variables in widgets
+```
+
+## Maintenance Principles
+
+- Keep package responsibilities clear. When migrating components, remove old
+  exports, styles, and theme variables from the previous package.
+- Keep single-component imports working. New components must not be available
+  only from package root exports.
+- Keep styles composable. Component CSS should not carry theme values directly.
+- Keep example coverage for all public components, especially widgets and
+  combined scenarios such as Mdx.
+- Keep broad component reviews focused on composition quality, API minimalism,
+  theme consistency, mobile behavior, documentation/demo alignment, and
+  self-hosting reuse.
+- Avoid unrelated renames and package configuration churn unless they are part
+  of the current task.

package/README.md

@@ -0,0 +1,27 @@
+<div align="center">
+<h2>willa</h2>
+
+[![NPM version](https://img.shields.io/npm/v/willa.svg?style=flat-square)](https://www.npmjs.com/package/willa)
+
+</div>
+
+Willa UI is a React component library for AI products, blogs, documentation
+sites, content platforms, MDX pages, and rich interactive content rendering.
+It provides layout primitives, form controls, product and content components,
+AI-oriented interaction patterns, small widget integrations, and shared
+utilities for building composable product and content experiences.
+
+**Online docs**: https://imtaotao.github.io/willa/
+
+## Development
+
+The `example` app demonstrates the public `willa` package and individual
+component imports.
+
+```bash
+# first time setup
+$ pnpm run build:packages
+
+# start the example dev server
+$ pnpm dev
+```

package/docs/architecture.md

@@ -0,0 +1,337 @@
+# Willa Architecture
+
+This document records Willa's repository structure, module responsibilities,
+dependency relationships, build flow, and common pitfalls. For new components,
+see [Willa Component Guide](./component.md). For CSS and theme rules, see
+[Willa CSS Guide](./css.md). For code style, see
+[Willa Style Guide](./style.md).
+
+## Project Scope
+
+Willa is a React component library for AI products, blogs, documentation sites,
+content platforms, MDX pages, and rich interactive content rendering. The core
+requirements are:
+
+- Components can be imported from package root entries.
+- Components can be imported from single-component entries.
+- Component CSS can be composed per component.
+- Light and dark theme CSS can be composed across packages.
+- Product interaction components and content rendering components can be
+  combined without crossing package ownership boundaries.
+- The example app can consume source code directly for development and docs.
+
+The repository is a pnpm workspace monorepo. Packages are built with `auklet`.
+
+## File Organization
+
+```text
+.
+  package.json
+  pnpm-workspace.yaml
+  tsconfig.json
+  CONTRIBUTING.md
+  docs/
+    architecture.md
+    component.md
+    css.md
+    style.md
+  example/
+    src/
+      catalog/
+      docs/
+  packages/
+    willa/
+      src/
+      auklet.config.mjs
+    willa-content/
+      src/
+        components/
+        themes/
+      auklet.config.mjs
+    willa-layout/
+      src/
+        components/
+        themes/
+      auklet.config.mjs
+    willa-form/
+      src/
+        components/
+        themes/
+      auklet.config.mjs
+    willa-ai/
+      src/
+        components/
+        themes/
+      auklet.config.mjs
+    willa-widgets/
+      src/
+        components/
+        themes/
+      auklet.config.mjs
+    willa-shared/
+      src/
+      auklet.config.mjs
+```
+
+The root directory contains workspace configuration, shared TypeScript
+configuration, repository documentation, and development commands. Packages do
+not maintain their own `tsconfig.json`; they use the root `tsconfig.json`.
+
+`docs` contains focused maintenance documents:
+
+- `architecture.md`: overall structure, module relationships, build flow, and
+  pitfalls.
+- `component.md`: component creation, migration, exports, and example rules.
+- `css.md`: CSS, theme variables, and cross-package style dependency rules.
+- `style.md`: TypeScript, React, and documentation code style.
+
+## Module Responsibilities
+
+`packages/willa` is the public aggregate package, published as `willa`. It
+exports aggregate components and does not export `@willa-ui/shared`. It usually
+does not own component implementations or theme variables; it combines selected
+layout, content, form, AI, and widgets outputs. AI components are implemented
+in `@willa-ui/ai`, then exposed through `willa` for public use.
+
+`packages/willa-content` is the base product and content component package,
+published as `@willa-ui/content`. It contains general product and content
+components such as `Button`, `CodeBlock`, `Callout`, `Image`, `Tabs`,
+`Dialog`, and `Steps`.
+
+`packages/willa-layout` is the layout component package, published as
+`@willa-ui/layout`. It contains layout primitives such as `Card`, `Group`,
+`Stack`, `Grid`, `Masonry`, `Container`, `Panel`, `Separator`, `SplitPane`,
+`ResizablePanel`, `BorderBeam`, `PageHeader`, `SectionHeader`, `AppShell`, and
+`SidebarLayout`. Layout components own their component-specific layout
+variables and the Willa base visual tokens such as fonts, text colors, lines,
+surfaces, and focus rings.
+
+`packages/willa-form` is the form component package, published as
+`@willa-ui/form`. It contains form controls and form layout components such as
+`Input`, `TextArea`, `Select`, `Checkbox`, `Radio`, `Switch`, `DatePicker`,
+`Upload`, `Form`, `FormField`, and `FormActions`. It can compose layout and
+content components and reuse their CSS through `styles.dependencies`, but
+layout and content must not depend on form.
+
+`packages/willa-ai` is the AI product component package, published as
+`@willa-ui/ai`. It contains AI-oriented scene components such as prompt inputs,
+chat messages, attachments, tool call displays, reasoning steps, generation
+cards, context panels, trace viewers, and related interaction patterns. It can
+compose layout and content components and reuse their CSS through
+`styles.dependencies`, but it must not make layout or content depend on AI.
+
+`packages/willa-widgets` is the scenario component package, published as
+`@willa-ui/widgets`. It contains platform integrations, MDX composition,
+external embeds, media-rich content blocks, and more domain-specific components
+such as `Mdx`, `GitHubRepo`, `XPostEmbed`, `WebEmbed`, `AudioEmbed`,
+`VideoEmbed`, `Poem`, and `EnglishCards`. It can compose layout, content, and
+form components, but layout, content, and form must not depend on widgets.
+
+`packages/willa-shared` is the shared utility package, published as
+`@willa-ui/shared`. It contains cross-package types, text utilities, node
+utilities, clipboard helpers, and similar logic. It does not contain React
+components or component CSS.
+
+`example` is the component demo and documentation app. In development, it
+consumes package source through tsconfig aliases. The default port is `2333`.
+
+## Dependency Relationships
+
+Dependencies must remain one-way:
+
+- shared does not depend on content, form, AI, or widgets.
+- content can depend on shared and layout.
+- layout can depend on shared.
+- form can depend on shared, layout, and content.
+- ai can depend on shared, layout, content, and form when it composes form
+  inputs.
+- widgets can depend on shared, layout, content, and form.
+- willa depends on layout, content, form, AI, and widgets as the public
+  aggregate package.
+- example can depend on all public packages and source aliases.
+
+Do not make layout or content depend on form, AI, or widgets. Do not move
+layout-specific, form-specific, AI-specific, or widget-specific variables,
+styles, or components back into content.
+
+```mermaid
+flowchart LR
+  shared["@willa-ui/shared"]
+  layout["@willa-ui/layout"]
+  content["@willa-ui/content"]
+  form["@willa-ui/form"]
+  ai["@willa-ui/ai"]
+  widgets["@willa-ui/widgets"]
+  willa["willa"]
+  example["example"]
+
+  content --> shared
+  content --> layout
+  layout --> shared
+  form --> shared
+  form --> layout
+  form --> content
+  ai --> shared
+  ai --> layout
+  ai --> form
+  ai --> content
+  widgets --> shared
+  widgets --> layout
+  widgets --> content
+  widgets --> form
+  willa --> layout
+  willa --> content
+  willa --> form
+  willa --> ai
+  willa --> widgets
+  example --> willa
+  example --> layout
+  example --> content
+  example --> form
+  example --> ai
+  example --> widgets
+  example --> shared
+```
+
+## Path Aliases
+
+Prefer source aliases over deep relative paths:
+
+- `#content/*` points to `packages/willa-content/src/*`
+- `#layout/*` points to `packages/willa-layout/src/*`
+- `#form/*` points to `packages/willa-form/src/*`
+- `#ai/*` points to `packages/willa-ai/src/*`
+- `#widgets/*` points to `packages/willa-widgets/src/*`
+- `#shared/*` points to `packages/willa-shared/src/*`
+- `#example/*` points to `example/src/*`
+- `@willa-ui/*` points to package source roots
+
+`willa/*` maps to single-component entries under `packages/willa/src/*`. When
+adding path rules, prefer wildcard mappings instead of one-off file mappings.
+
+## Build Relationships
+
+Every publishable package uses `auklet.config.mjs`. `modules: true` generates
+single-component entries. `styles.themes` declares the package's own theme CSS.
+`styles.dependencies` declares cross-package CSS dependencies.
+
+Core build outputs include:
+
+- Package root entries, such as `@willa-ui/content`.
+- Single-component entries, such as `willa/CodeBlock`.
+- Package root CSS, such as `willa/style.css`.
+- Single-component CSS, such as `willa/CodeBlock.css`.
+- Theme CSS, such as `willa/themes/light.css` and `willa/themes/dark.css`.
+
+```mermaid
+flowchart TB
+  source["src components and themes"]
+  auklet["auklet build"]
+  js["JS entries"]
+  css["CSS entries"]
+  root["package root export"]
+  modules["single component exports"]
+  themes["theme css"]
+
+  source --> auklet
+  auklet --> js
+  auklet --> css
+  js --> root
+  js --> modules
+  css --> themes
+  css --> modules
+```
+
+## CSS Composition Flow
+
+CSS composition is driven by `styles.dependencies` in `auklet.config.mjs`.
+Content, form, AI, and widgets depend on layout CSS for base visual tokens and
+layout component styles. Form, AI, and widgets also depend on content CSS when
+they compose content components. AI and widgets can also depend on form CSS
+when they compose form components. willa composes public package CSS.
+
+```mermaid
+flowchart LR
+  layoutCss["layout CSS and themes"]
+  contentOwn["content own CSS and themes"]
+  contentCss["content output CSS"]
+  formOwn["form own CSS and themes"]
+  formCss["form output CSS"]
+  aiOwn["AI own CSS and themes"]
+  aiCss["AI output CSS"]
+  widgetsOwn["widgets own CSS and themes"]
+  widgetsCss["widgets output CSS"]
+  willaCss["willa output CSS"]
+
+  layoutCss --> contentCss
+  contentOwn --> contentCss
+  layoutCss --> formCss
+  contentCss --> formCss
+  formOwn --> formCss
+  layoutCss --> aiCss
+  contentCss --> aiCss
+  aiOwn --> aiCss
+  layoutCss --> widgetsCss
+  contentCss --> widgetsCss
+  formCss --> widgetsCss
+  widgetsOwn --> widgetsCss
+  layoutCss --> willaCss
+  contentCss --> willaCss
+  formCss --> willaCss
+  aiCss --> willaCss
+  widgetsCss --> willaCss
+```
+
+This means higher-level packages can reference base visual tokens from layout
+and component variables from their direct CSS dependencies. They must not copy
+layout or content variable definitions. willa only composes CSS and does not
+own component theme variables.
+
+## Example Documentation Flow
+
+Example documentation data lives in `example/src/docs`. The registry lives in
+`example/src/catalog/registry.ts`. `registry.ts` keeps lightweight entries and
+loads demos dynamically through `load`, so component code and CSS do not all
+enter the initial page.
+
+```mermaid
+flowchart LR
+  registry["catalog registry"]
+  doc["ComponentName.demo.tsx"]
+  defineDoc["defineDoc"]
+  view["DocView"]
+  preview["live preview"]
+  code["generated code"]
+
+  registry --> doc
+  doc --> defineDoc
+  defineDoc --> view
+  view --> preview
+  view --> code
+```
+
+## Pitfalls
+
+- Do not make layout or content depend on form, AI, or widgets. Do not make form
+  depend on AI or widgets. layout is the base visual layer, content is the base
+  product/content layer, form is the form layer, and AI and widgets are scenario
+  layers. Reversing this makes lower packages heavier and breaks
+  single-component CSS composition.
+- Do not copy layout or content variables into higher-level package themes.
+  They already depend on upstream CSS and themes through
+  `styles.dependencies`; duplicate definitions make theme sources inconsistent.
+- Do not add component theme variables to the willa aggregate package. willa
+  only combines public package CSS; component variables should follow the
+  package that owns the component source.
+- Do not add per-package `tsconfig.json` files. Current aliases, strict checks,
+  and example source consumption depend on the root TypeScript config.
+- Do not change `auklet.config.mjs` back to TypeScript. The current auklet
+  version does not support `auklet.config.ts`; use `.mjs` and `defineConfig`.
+- Do not validate only package root entries. New public components must verify
+  package root imports, willa root imports, willa single-component imports, and
+  single-component CSS imports.
+- Do not make `registry.ts` statically import demos. Example demos should load
+  only when selected.
+- Portal component theme variables cannot live only on `.willa-shell`. For
+  example, `Lightbox` renders into `document.body`, so the variable scope must
+  also cover the component root.