@commenda/pathfinder 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,6 @@
+# @commenda/pathfinder
+
+## 0.1.0
+
+Initial public registry release of Commenda's design system: React components,
+AI elements, icons, compiled styles, local fonts, and TypeScript declarations.

package/README.md

@@ -1,3 +1,260 @@
-# Temporary Holding Version
+# Pathfinder
 
-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.
+`@commenda/pathfinder` is Commenda's new React design-system package. It ships
+compiled ESM, TypeScript declarations, and a finished Tailwind v4 stylesheet.
+Components expose typed public APIs and compile their styles for use in consumer applications.
+
+## Installation and releases
+
+The package is configured for public npm distribution. After the first release,
+run `pnpm add @commenda/pathfinder`; no npm login or installation token is needed. Inside this monorepo, keep using `workspace:*`.
+
+See the [installation guide](https://pathfinder.commenda.io/docs/getting-started/installation)
+for setup and stylesheet imports. Maintainers can follow
+[Publishing Pathfinder](https://github.com/commenda-eng/commenda/blob/main/packages/pathfinder/PUBLISHING.md) in the source repository for initial npm
+setup and the release workflow.
+
+## Use in an application
+
+```tsx
+// Pages Router: pages/_app.tsx. App Router: app/layout.tsx.
+import '@commenda/pathfinder/styles.css';
+```
+
+```tsx
+import { Button } from '@commenda/pathfinder';
+
+export const SaveButton = () => <Button>Save changes</Button>;
+```
+
+Interactive event handlers must live in a client component in App Router apps.
+The published Button entry retains `use client`; the root barrel does not force
+future server-compatible components into a client boundary. A direct
+`@commenda/pathfinder/button` import is also supported.
+
+Consumers need no Tailwind dependency, source scanning, PostCSS plugin, or
+`transpilePackages` entry for Pathfinder. Import the stylesheet after your app's
+base stylesheet. Next.js still bundles the finished CSS as part of its build.
+
+## Navigation and display components
+
+Import `Separator`, `Breadcrumb`, `Tabs`, `Stepper`, `Accordion`, `Badge`,
+`Card`/`StatCard`, and `Avatar`/`AvatarGroup` from the root or their component
+subpaths (`@commenda/pathfinder/tabs`, for example).
+
+Tabs and Accordion accept typed item arrays and enforce controlled/uncontrolled
+selection contracts. Avatar accepts a person/organization/logo `identity` union.
+Card groups related options in `headerConfig`, `footerConfig`, and `scrollConfig`;
+Breadcrumb and StatCard use `linkConfig` for native destinations and router adapters.
+
+See the [component documentation](../../apps/pathfinder-docs/content/docs/components/)
+for props, examples, and Figma-derived rules.
+Storybook groups these under Navigation, Disclosure, Layout, and Display. Fumadocs
+provides matching previews, formatted source, props/defaults, and AI-readable rules.
+
+The new example snippets are generated from the actual rendered examples. After
+editing `documentation/navigation/*Examples.tsx`, run `pnpm generate:examples`
+from this package; `check:examples` prevents stale copied code during builds.
+
+## Workspace development
+
+Follow the [contribution guide](../../apps/pathfinder-docs/content/docs/guides/contributing.mdx)
+for component structure, TypeScript rules, skill guidance, and required checks.
+
+From the repository root:
+
+```sh
+pnpm pathfinder:build
+pnpm pathfinder:dev
+pnpm pathfinder:docs
+pnpm pathfinder:storybook
+pnpm --filter commenda-enterprise dev
+pnpm --filter @commenda/pathfinder test
+```
+
+Run the watcher and enterprise dev server in separate terminals. Enterprise's
+dev/build/check-types commands build Pathfinder first, including on a clean
+checkout. Turbo also builds Pathfinder before its consumers.
+
+`pathfinder:dev` only watches package output; it has no HTTP port. Fumadocs runs
+on **3002** and Storybook runs on **6006**. Storybook starts its own package
+watcher, so a separate `pathfinder:dev` is not needed when using Storybook alone.
+Normal builds and watchers do not delete `dist`, avoiding output deletion while
+a consumer is running. After removing or renaming source modules, stop watchers
+and remove obsolete generated files before packing.
+
+Enterprise uses Webpack for local development because Turbopack currently fails
+while compiling its dependency graph. Run these commands without `sudo` so build
+outputs remain writable by your user.
+
+Use Fumadocs at `http://localhost:3002/docs` for component examples and props,
+and Storybook at `http://localhost:6006` for interactive and worst-case testing.
+The enterprise `/pathfinder` demo page has been removed; demo components live
+only in the documentation/playground tooling.
+
+Token CSS is generated from `src/foundations` at build time. After editing tokens
+or build configuration, restart the watcher. No Commenda workspace dependency is
+required at runtime by the published package.
+
+## Styling contract
+
+- Pathfinder compiles its own Tailwind v4 styles. The docs app also uses v4 for
+  its shell; consumers can use the compiled stylesheet without a Tailwind installation.
+- Utilities and theme variables use the `pf` prefix. No Preflight is included.
+- Override semantic variables such as `--pf-color-primary` on a theme container.
+- Font defaults to Inter. Optionally import `@commenda/pathfinder/fonts.css` for self-hosted Inter, or provide `--font-inter` from the host font loader. System fonts remain the fallback.
+- `className` is additive. Conflicting host utilities follow the CSS cascade;
+  they are not automatically merged or guaranteed to override internal classes.
+- Supported browser baseline: Safari 16.4+, Chrome 111+, Firefox 128+.
+- Only the existing light theme is supplied in this foundation release.
+
+## Foundations
+
+The reviewed Figma source lives in `src/foundations`: 81 scale/background colors,
+eight avatar pairs, 17 Inter styles, spacing, radius, control/icon/container sizes,
+strokes, breakpoints, elevation and motion. Existing app tokens are not modified.
+
+```tsx
+import { colors, typography, spring } from '@commenda/pathfinder/tokens';
+import '@commenda/pathfinder/styles.css';
+import '@commenda/pathfinder/fonts.css'; // Optional self-hosted normal Inter.
+
+export const Title = () => <h1 className="pf-txt-heading-24">Entities</h1>;
+```
+
+All `pf-txt-*` classes ship precompiled; choose semantic HTML independently.
+`@commenda/pathfinder/tokens.json` provides the same values, source node IDs and
+unit metadata for tooling and AI. Durations use milliseconds; spring durations
+use seconds. No motion library or automatic animation ships with the tokens.
+
+Legacy Button color override variables remain available, now referencing the new
+scales. Its baseline is Inter Label/13 Strong (13/16 at weight 500), so the default
+button is now 32px tall at the 16px root. Long labels still wrap and increase height.
+Dark mode is deferred by the Figma specification. See Fumadocs Foundations and
+Storybook Foundations/Start here for reference tables and specimens.
+
+## Distribution
+
+```sh
+pnpm --dir packages/pathfinder pack --pack-destination /tmp
+```
+
+Packing rebuilds the package. Only `dist`, this README, and package metadata ship.
+React and React DOM are peer dependencies; Base UI is a runtime dependency.
+The package is publishable but has not been published. Registry/access settings
+and release automation will be configured before the first release.
+
+## Verification
+
+```sh
+pnpm pathfinder:lint
+pnpm --filter @commenda/pathfinder lint:fix
+pnpm --filter @commenda/pathfinder test
+pnpm --filter @commenda/pathfinder check-types
+pnpm --filter @commenda/pathfinder test:package
+PATHFINDER_NEXT_SMOKE=1 pnpm --filter @commenda/pathfinder test:package
+pnpm pathfinder:docs:build
+pnpm pathfinder:storybook:build
+```
+
+The package tests cover behavior, compiled CSS/client boundaries, and public
+types under Bundler and NodeNext resolution. Packed-consumer tests install a
+tarball outside the workspace with React 18 and 19. The optional Next.js check
+builds Pages Router fixtures and an App Router server-component import without
+Tailwind. Fixture directories are retained in the system temporary directory.
+
+Source components, stories, and behavior tests are colocated under
+`src/components/<component>`. Build helpers and test configuration have separate
+TypeScript checks; they are excluded from declaration output.
+
+## Lint standards
+
+Pathfinder and its docs use a scoped ESLint 9 flat configuration; existing apps
+keep their own lint setup. CI rejects warnings as well as errors. Rules cover
+strict type-aware TypeScript (including unsafe `any`, unhandled promises and
+exhaustive switches), explicit type imports/exports, React hooks, accessible JSX,
+unused imports, and component package boundaries. Components cannot import Next.js,
+application code, private workspace packages, or generated output. Build-time token
+helpers remain outside component source.
+
+Generated files and isolated consumer fixtures are excluded. Fixtures are checked
+by their own compiler/build tests. Stories and tests keep type checking and lint;
+only unbound-method checks are relaxed for mock assertions. Inline ESLint disables
+are rejected; document any necessary exception in the scoped config. Accessibility
+lint complements Storybook accessibility checks and keyboard tests.
+
+## Planned follow-up
+
+Figma-based component styles, additional primitives, visual regression baselines,
+Changesets publishing, archived documentation versions, and optional MCP support
+follow this foundation. Current AI documentation includes package version metadata
+but does not yet retain historical releases.
+
+## Foundation source layout
+
+Each foundation keeps its token definitions and Storybook specimens together:
+
+```text
+src/foundations/
+  index.ts
+  color/        color-tokens.ts, Color.stories.tsx
+  typography/   typography-tokens.ts, Typography.stories.tsx
+  sizing/       sizing-tokens.ts, Sizing.stories.tsx
+  elevation/    elevation-tokens.ts, Elevation.stories.tsx
+  motion/       motion-tokens.ts, Motion.stories.tsx
+  overview/     StartHere.stories.tsx
+  shared/       foundations.stories.css
+```
+
+Edit a domain's token file to change values, and its colocated story to change examples. Stories import their domain directly. `foundations/index.ts` assembles the public `/tokens` interface and source provenance; consumers continue using the package exports. The `shared` folder contains specimen-only styling. Keep runtime token definitions independent of stories and React. Add a new domain when it has its own concepts and examples; individual scale entries do not need separate files or folders.
+
+## Visual assets
+
+Import finished styles once, then use a collection or individual component:
+
+```tsx
+import '@commenda/pathfinder/styles.css';
+import { SearchMdIcon } from '@commenda/pathfinder/icons/SearchMdIcon';
+import { USFlag } from '@commenda/pathfinder/flags/USFlag';
+
+<SearchMdIcon size={16} tone="brand" />
+<USFlag size={24} label="United States" />
+```
+
+Collections: `/icons`, `/flags`, `/file-types`, `/status-icons`, and `/logos/{integrations,payments,software,commenda}`. `/flags/dynamic` explicitly opts into the full flag registry for unknown-at-build-time country codes. `/assets.json` is the versioned source/import manifest. Assets render native inline SVG and accept `width`, `height`, and native SVG attributes. Simple glyphs stay server-compatible; artwork with masks/gradients uses a narrow client boundary with SSR-safe instance IDs. Both can be imported from server components; no SVG loader, consumer CSS compilation, remote images, or asset-copy step is required.
+
+Keep one source for verified scalable artwork and use render dimensions for sizing. Optical variants and non-equivalent layouts retain their own source. Flags and scalable integration marks get their fixed hairline from compiled CSS. Repeated drawings share generated artwork modules. See [the source guide](assets/README.md) for extraction, deduplication, checksums, and regeneration.
+
+Storybook has separate searchable libraries under **Assets**, with compact category grids, size previews, searchable names, and a keyboard-accessible dialog for copyable imports and Figma links. Fumadocs exposes the same explorers alongside rules and examples at `/docs/assets`. Collection code loads separately. Set `STORYBOOK_DOCS_URL` when building a hosted Storybook to point its usage links at the deployed docs; local links default to port 3002. The asset rules and full import inventory flow into `llms.txt`, `llms-full.txt`, and page Markdown.
+
+### Category imports
+
+```tsx
+import { Icons } from '@commenda/pathfinder';
+
+<Icons.Flags.US label="United States" />
+<Icons.Interface.SearchMd size={16} tone="quiet" />
+<Icons.FileTypes.Pdf />
+<Icons.Folder status="open" />
+<Icons.Status status="completed" label="Completed" />
+<Icons.Progress.Ring value={33} label="Documents complete" />
+<Icons.Logos.Integrations.Quickbooks />
+```
+
+`Icons.Logos` also includes `Payments`, `Software`, and `Commenda`. These are ESM namespace exports with the same props as individual components. Use static member access for tree shaking. Passing or dynamically indexing entire namespaces may retain additional artwork. The asset manifest includes every namespace path; existing named and direct imports remain supported.
+
+### Styling contributions
+
+Use `pf:` Tailwind v4 utilities and Pathfinder tokens for runtime components. Keep genuinely shared class recipes next to their consumers; retain CSS only for foundations, fonts, keyframes, and documented exceptions. The package compiles all utilities into `styles.css`; consumers need no Tailwind configuration. See the Fumadocs contribution guide for state, RTL, formatting, and packed-artifact checks.
+
+## AI content
+
+Import `Markdown`, `CodeBlock`, and `InlineReference` from their `markdown`, `code-block`, and `inline-reference` subpaths. They use the existing compiled stylesheet. Optionally import `@commenda/pathfinder/code-font.css` for the Figma Geist Mono font.
+
+The new code renderer uses Lowlight/Highlight.js. Streaming Markdown uses Streamdown without enabling its math or diagram plugins. Applications retain message IDs, message parts, routing, and orchestration. Existing consumers are not migrated. See the Fumadocs AI content integration guide for compatibility mappings.
+
+Markdown is intentionally available through `@commenda/pathfinder/markdown` only (its types are also exported from the root). Streamdown has module side effects; keeping this runtime off the root barrel prevents unrelated icon and button imports from loading the Markdown parser.
+
+AI input context is available from `/attachment`, `/attachment-group`, and `/composer-context` (also exported from the root). Attachments preserve host IDs, filenames, upload state, and callbacks; validation and responsive overflow are included, while uploads and viewer content remain app-owned. See the corresponding component docs for migration mappings and Figma rules.
+
+AI drafting exports: `/composer`, `/suggested-prompt`, and `/suggested-prompt-group`. Composer uses a controlled string draft and AI SDK-compatible request statuses, composes attachments and context, and leaves uploads, request errors, dictation, and clearing to the host. See the corresponding docs for skill search and migration mapping.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,25 @@
+# Pathfinder artwork provenance
+
+Interface glyphs derived from `@untitled-ui/icons-react` 0.1.4 carry the Devias MIT notice in `assets/licenses/untitled-ui.txt`. Flags derive from `country-flag-icons` 1.5.19 and carry the notice in `assets/licenses/country-flag-icons.txt`. The source package versions match the workspace lockfile and the Figma documentation.
+
+Commenda and Pathfinder additions, file artwork, and status artwork come from Commenda's The System Figma file. This package remains UNLICENSED; it does not grant third-party redistribution rights to Commenda artwork. Integration and payment marks remain their owners' trademarks. Their inclusion identifies integrations and payment methods and is not a general license to reuse brand artwork.
+
+The versioned catalog records original Figma node IDs, retained-source SHA-256 checksums, and verified artwork reuse. Shared drawings keep their semantic names. See the catalog for availability and explicit exclusions.
+
+Sonner 2.0.7 by Emil Kowalski is MIT licensed. Its scoped structural stylesheet is included for toast positioning and stack animation; see assets/licenses/sonner.txt. Toast glyph SVGs come from Figma node 464:357 (children 464:347, 464:350, 464:353, 464:356).
+
+AddressInput's generated region names and codes come from country-state-city 3.2.1, with Pathfinder's explicit US territory exclusions. Its GPL-3.0 license is retained in assets/licenses/country-state-city.txt. Pathfinder includes region metadata only; the provider's JavaScript, city database, and coordinates are not shipped.
+
+## Vercel AI Elements — AI content behavior
+
+Source reference: https://github.com/vercel/ai-elements/tree/6a9d5b1822ffb10bba4bd97175f01edd7d8651cd/packages/elements/src
+
+Copyright 2023 Vercel, Inc. Apache-2.0; notice in `assets/licenses/ai-elements.txt`.
+
+Pathfinder's Markdown follows MessageResponse's Streamdown composition. CodeBlock follows its source-copy and highlighted-token rendering behavior, with a fresh direct-prop implementation. Modifications: Pathfinder controls and Figma typography, Lowlight/Highlight.js replacing Shiki, no default math/diagram plugins, React 18 compatibility, exact-source copy, typed reference resolution, and no text-only memo comparator. Upstream source is a reference, not an automatically updated runtime copy.
+
+Phase 2 attachment APIs were informed by the existing Vercel AI Elements attachment composition in `packages/ui/commenda-ai/ai-elements/attachment.tsx`. Pathfinder uses its own direct item/callback API and existing Pathfinder file icons, progress, preview and sheet primitives. Upload transports, source-document rendering, viewer dependencies, and application providers are not copied.
+
+### Phase 3 interaction references
+
+Composer and SuggestedPrompt were implemented for Pathfinder's controlled API and Figma specification, informed by Vercel AI Elements Prompt Input and Suggestion documentation (https://elements.ai-sdk.dev/components/prompt-input and https://elements.ai-sdk.dev/components/suggestion, reviewed 2026-10-13). No AI Elements implementation source was copied for these components. Base UI supplies popover positioning and existing Pathfinder controls. No Shiki dependency was introduced.

package/assets/licenses/ai-elements.txt

@@ -0,0 +1,13 @@
+Copyright 2023 Vercel, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/assets/licenses/country-flag-icons.txt

@@ -0,0 +1,22 @@
+(The MIT License)
+
+Copyright (c) 2020 @catamphetamine <purecatamphetamine@gmail.com>
+
+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.