@oddkin/components 0.0.0-stage → 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brian Brady
+
+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,60 @@
-# Temporary Holding Version
+# @oddkin/components
 
-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.
+Themed custom elements, Oddkin layout presets, and component metadata. Accessibility is tested with keyboard checks and axe-core audits in Chromium, Firefox, and WebKit; screen readers are not yet verified ([support policy](../../docs/support.md#accessibility)).
+
+**Status:** beta, published under npm's `beta` tag. 54 elements, each listed with its contract in `custom-elements.json` and `oddkin.metadata.json`. See [IMPLEMENTATION_PLAN.md](../../IMPLEMENTATION_PLAN.md) and [packages.md](../../docs/architecture/packages.md).
+
+## Use
+
+```js
+import '@oddkin/components/define/button'; // registers <odd-button>
+```
+
+```html
+<odd-button appearance="primary" type="submit" name="intent" value="save">Save</odd-button>
+```
+
+Importing `@oddkin/components/button` gives the class, template, styles, and definition without registering anything. `@oddkin/components/button/foundation` gives the behavior class, template, and structural styles without the default visual styles, for product-specific skins composed with `compose()` (see [multi-product.md](../../docs/architecture/multi-product.md)).
+
+Styles read semantic tokens through component variables (`--odd-button-radius`, `--odd-button-background`, …), so a theme or a scoped override restyles the button without JavaScript. Load a theme stylesheet such as `@oddkin/tokens/css/default.css`.
+
+## Autoload (optional)
+
+```js
+import '@oddkin/components/autoload'; // registers each odd-* element on its first appearance
+```
+
+The autoloader imports an element's `define/<name>` entry when its tag first appears in the document, once per tag, resolved relative to the autoloader so import maps and CDNs serve the same files. Call `observe(shadowRoot)` for shadow roots your page creates; `load(tag)` registers one tag ahead of time. An `odd-*` tag that is not an Oddkin element is reported once (`autoload.tag.unknown`, through `@oddkin/core/diagnostics`).
+
+Use it for markup you do not control the imports of: content written by people or agents, prototypes, CMS pages. For an application, import each `define/<name>` you use: a bundler sees them, the browser can preload them, and nothing is fetched after the first render. Measured with the same five elements under a strict CSP: two more module requests (the autoloader and its list of names), and the definitions start loading only once it runs (`e2e/autoload.spec.ts`).
+
+## Side navigation from data
+
+```js
+import '@oddkin/components/define/side-nav';
+import { NavigationItemModel } from '@oddkin/components/models'; // only to validate external data
+
+const nav = document.querySelector('odd-side-nav');
+const result = NavigationItemModel.validate(await (await fetch('/nav.json')).json());
+if (result.ok) nav.items = result.value; // replace the array to change entries; never mutate it
+nav.current = 'theming';
+nav.addEventListener('odd-action', (e) => run(e.detail.action));
+```
+
+Links render as native `<a href>` (script URLs never do), actions as buttons that emit `odd-action`, and groups as disclosure buttons. Without `items`, native links in the default slot are styled instead; `header` and `footer` slots work with both. Set `expanded` to own group expansion yourself; otherwise the element tracks it and emits a cancelable `odd-toggle`. The `side-nav` layout recipe arranges entries by the element's own width (container queries only). The JSON Schema for the same model is `@oddkin/components/schemas/oddkin.navigation.v1.json`.
+
+## Shared styles for your own components and pages
+
+```js
+import { hostStyles, focusRingStyles, visuallyHiddenStyles } from '@oddkin/components/styles';
+// styles: [hostStyles, myStructuralStyles, focusRingStyles, visuallyHiddenStyles, myStyles]
+```
+
+Each primitive is one constructed sheet per document, shared by every component that adopts it. For pages, opt in to `@oddkin/components/css/reset.css`, `base.css` (theme-driven body text, links, focus ring), and `utilities.css` (`.odd-visually-hidden`, `.odd-focus-ring`); each sits in its Oddkin cascade layer, so unlayered page CSS overrides it.
+
+## Styling and browser support
+
+- Customize through inherited tokens, documented component variables, host styles, parts, and custom states: `odd-input:state(user-invalid)::part(control) { … }` styles the field while it shows its error (the same state that sets `aria-invalid`).
+- Unlayered page CSS overrides the generated tokens (they sit in the `odd.tokens` layer); page selectors never reach inside a component.
+- Hover feedback appears only where the primary pointer can hover; focus rings are outlines and stay visible in forced-colors mode; long labels and URLs wrap inside narrow containers; sizes are in `rem` and targets never fall below the target-size token.
+- Supported browsers: Chrome and Edge 130, Firefox 132, Safari 18.2 and later (mobile equivalents included). See [css-architecture.md](../../docs/architecture/css-architecture.md) and the [platform feature matrix](../../docs/compatibility/matrix.md).

package/agent/GUIDE.md

@@ -0,0 +1,41 @@
+# @oddkin/components 1.0.0-beta.1: agent guide
+
+Generated from this package's published metadata when it was built (fingerprint in kit.json), so it matches the installed version. Read the reference for a component before using it.
+
+## Install and register
+
+- Package `@oddkin/components`, which depends on `@oddkin/core`, `@oddkin/tokens`.
+- Register an element once before using its tag: `import '@oddkin/components/define/<name>';`, where `<name>` is the tag after its prefix (`<odd-alert>`: `import '@oddkin/components/define/alert';`). Class exports are in each component reference.
+- Link the theme's stylesheet once per document, `@oddkin/tokens/css/default.css`: the design tokens every component reads.
+- Without a bundler, an import map must map every bare specifier a page loads, the packages' own imports included (`@oddkin/core/…`, `@oddkin/tokens/…`), to the file each package's `exports` names under the `default` condition. Never mix in a `development` build: it is a second copy of the package.
+
+## Components
+
+Each has a reference at `references/components/<tag>.md` with its exact API, guidance, and examples.
+
+- **Actions:** `<odd-button>`, `<odd-command-palette>`, `<odd-copy-button>`, `<odd-menu>`, `<odd-split-button>`, `<odd-toolbar>`
+- **Collections:** `<odd-tree>`
+- **Containers:** `<odd-card>`
+- **Display:** `<odd-avatar>`, `<odd-chip>`, `<odd-icon>`, `<odd-relative-time>`, `<odd-stat>`, `<odd-status-marker>`
+- **Feedback:** `<odd-alert>`, `<odd-badge>`, `<odd-empty-state>`, `<odd-progress>`, `<odd-skeleton>`, `<odd-spinner>`
+- **Forms:** `<odd-calendar>`, `<odd-checkbox>`, `<odd-checkbox-group>`, `<odd-color-picker>`, `<odd-combobox>`, `<odd-date-picker>`, `<odd-file-input>`, `<odd-input>`, `<odd-listbox>`, `<odd-one-time-code>`, `<odd-picker>`, `<odd-radio-group>`, `<odd-rating>`, `<odd-segmented-control>`, `<odd-select>`, `<odd-slider>`, `<odd-switch>`, `<odd-textarea>`, `<odd-validation-summary>`
+- **Layout:** `<odd-container>`, `<odd-scroll-region>`, `<odd-split-panel>`
+- **Navigation:** `<odd-breadcrumbs>`, `<odd-carousel>`, `<odd-disclosure>`, `<odd-pagination>`, `<odd-side-nav>`, `<odd-tab-panel>`, `<odd-tabs>`
+- **Overlays:** `<odd-dialog>`, `<odd-drawer>`, `<odd-popover>`, `<odd-toast>`, `<odd-tooltip>`
+
+Choosing between them: references/choosing-components.md.
+
+## Rules from the metadata
+
+- Property-only values (assign as JavaScript properties, never attributes): `odd-breadcrumbs.items`, `odd-breadcrumbs.strings`, `odd-calendar.isDateDisabled`, `odd-calendar.strings`, `odd-calendar.value`, `odd-carousel.strings`, `odd-checkbox.checked`, `odd-chip.strings`, `odd-color-picker.options`, `odd-color-picker.strings`, `odd-color-picker.value`, `odd-combobox.options`, `odd-combobox.strings`, `odd-combobox.values`, `odd-command-palette.items`, `odd-command-palette.strings`, `odd-copy-button.strings`, `odd-date-picker.isDateDisabled`, `odd-date-picker.strings`, `odd-date-picker.value`, `odd-dialog.returnValue`, `odd-dialog.strings`, `odd-drawer.returnValue`, `odd-drawer.strings`, `odd-file-input.strings`, `odd-input.strings`, `odd-input.value`, `odd-input.valueAsNumber`, `odd-listbox.options`, `odd-listbox.strings`, `odd-listbox.values`, `odd-menu.items`, `odd-one-time-code.strings`, `odd-one-time-code.value`, `odd-pagination.strings`, `odd-picker.expanded`, `odd-picker.items`, `odd-picker.options`, `odd-picker.strings`, `odd-picker.values`, `odd-popover.anchorElement`, `odd-popover.strings`, `odd-progress.renderValue`, `odd-progress.strings`, `odd-radio-group.options`, `odd-rating.options`, `odd-rating.strings`, `odd-relative-time.strings`, `odd-scroll-region.strings`, `odd-segmented-control.options`, `odd-select.options`, `odd-side-nav.expanded`, `odd-side-nav.items`, `odd-side-nav.kinds`, `odd-side-nav.renderLabel`, `odd-slider.renderValue`, `odd-slider.value`, `odd-slider.valueAsNumber`, `odd-spinner.strings`, `odd-split-button.items`, `odd-split-button.strings`, `odd-split-panel.strings`, `odd-stat.strings`, `odd-switch.checked`, `odd-switch.strings`, `odd-textarea.strings`, `odd-textarea.value`, `odd-toast.strings`, `odd-tooltip.anchorElement`, `odd-tree.expanded`, `odd-tree.items`, `odd-tree.strings`, `odd-tree.values`, `odd-validation-summary.strings`.
+- Events declared with user intent (authored; see each reference): `change`, `input`, `odd-chip-remove`, `odd-query-change`, `odd-action`, `odd-copy`, `odd-toggle`. Other events state their intent, or that it is unknown, in each reference.
+- Contracts the components reference (`@oddkin/core/CONTRACTS.md`): `contract:core/binding-rule` Binding rule; `contract:core/properties` Public properties; `contract:core/events` Events; `contract:core/lifecycle` Lifecycle; `contract:core/update-complete` updateComplete and commit timing; `contract:core/scope` Scope: ownership and cleanup; `contract:core/composition` Composed definitions.
+
+## More references
+
+- Tokens (theme `default`): references/tokens/component.md, references/tokens/foundation.md, references/tokens/layout.md, references/tokens/reference.md, references/tokens/semantic.md.
+- Recipes: references/recipes/alert.md, references/recipes/breadcrumbs.md, references/recipes/calendar.md, references/recipes/checkbox-group.md, references/recipes/color-picker.md, references/recipes/combobox.md, references/recipes/command-palette.md, references/recipes/dialog.md, references/recipes/disclosure.md, references/recipes/empty-state.md, references/recipes/file-input.md, references/recipes/listbox.md, references/recipes/pagination.md, references/recipes/progress.md, references/recipes/radio-group.md, references/recipes/rating.md, references/recipes/scroll-region.md, references/recipes/side-nav.md, references/recipes/slider.md, references/recipes/stat.md, references/recipes/toolbar.md, references/recipes/tree.md, references/recipes/validation-summary.md.
+- Document stylesheets (opt-in CSS: reset, layout classes, native-element recipes): references/stylesheets/avatar-group.md, references/stylesheets/base.md, references/stylesheets/button.md, references/stylesheets/description-list.md, references/stylesheets/divider.md, references/stylesheets/field.md, references/stylesheets/kbd.md, references/stylesheets/layout.md, references/stylesheets/link.md, references/stylesheets/list.md, references/stylesheets/reset.md, references/stylesheets/stepper.md, references/stylesheets/table.md, references/stylesheets/timeline.md, references/stylesheets/typography.md, references/stylesheets/utilities.md.
+- Interfaces as data (validate and render JSON documents): references/composition.md.
+- Models: references/models/oddkin.navigation.md.
+- JSON keyed by stable id, shipped beside this kit: `@oddkin/components/oddkin.metadata.json` (components, recipes, stylesheets, models), `@oddkin/components/custom-elements.json`, and the theme's tokens in `@oddkin/tokens/inspect/default.json`.