@vraxis/osx-components 0.11.3

package/LICENSE

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

@@ -0,0 +1,214 @@
+# OSX Components
+
+OSX Components is an open-source collection of OS X-inspired web components authored with Vue 3. Components render through the Custom Elements API, so they work in Vue, React, Svelte, Astro, or plain HTML.
+
+The project recreates the interaction language—not Apple assets or source code—with accessible controls, Shadow DOM encapsulation, and a shared token contract.
+
+## Install
+
+```bash
+npm install @vraxis/osx-components
+```
+
+```ts
+import { registerOsxComponents } from "@vraxis/osx-components";
+import "@vraxis/osx-components/theme.css";
+
+registerOsxComponents();
+```
+
+## Build with an AI agent
+
+Install the versioned `build-with-osx-components` skill so coding agents select real components, follow the theme and accessibility contracts, and verify the finished interface instead of approximating the system from screenshots.
+
+```bash
+# Portable Agent Skills location; works with compatible agents
+npx @vraxis/osx-components agent install
+
+# Agent-specific project installation
+npx @vraxis/osx-components agent install --target codex
+npx @vraxis/osx-components agent install --target claude
+npx @vraxis/osx-components agent install --target opencode
+npx @vraxis/osx-components agent install --target cursor
+
+# Install every project adapter
+npx @vraxis/osx-components agent install --target all
+```
+
+Use `--scope user` with `agents`, `codex`, `claude`, or `opencode` to install the skill globally. Re-run with `--force` after upgrading the package. Cursor rules remain project scoped.
+
+The skill includes component-selection guidance, framework integration patterns, application and agent-workspace compositions, the project quality standard, and a deterministic interface audit:
+
+```bash
+npx @vraxis/osx-components agent install --target agents
+node .agents/skills/build-with-osx-components/scripts/audit-osx-ui.mjs .
+```
+
+```html
+<div data-osx-theme="aqua">
+  <osx-window title="Preferences" subtitle="Appearance">
+    <osx-toolbar slot="toolbar">
+      <strong slot="leading">General</strong>
+      <osx-button slot="trailing" size="small">Show All</osx-button>
+    </osx-toolbar>
+    <osx-button variant="primary">Save changes</osx-button>
+  </osx-window>
+</div>
+```
+
+## Themes
+
+Set `data-osx-theme` on any ancestor. Tokens inherit across each component's Shadow DOM boundary.
+
+- `aqua` — bright blue, translucent highlights, and cool raised surfaces
+- `graphite` — the Aqua structure with a neutral accent system
+- `panther` — a dark interpretation designed as if the original system had shipped one
+
+Every visual decision is exposed through `--osx-*` custom properties. Override the tokens on an application shell or an individual component.
+
+## Components
+
+| Element | Purpose |
+| --- | --- |
+| `<osx-app-shell>` | Responsive application workspace with toolbar, sidebar, content, composer, inspector, status slots, and optional accessible panel resizing |
+| `<osx-agent-composer>` | Prompt input with Enter-to-send, busy state, model context, and stop action |
+| `<osx-agent-message>` | User, assistant, system, streaming, and error conversation states |
+| `<osx-agent-run-status>` | Plan, work, verify, complete, and failure lifecycle visualization |
+| `<osx-agent-approval>` | Risk-aware human approval with explicit action scope |
+| `<osx-thinking>` | Collapsible, streaming reasoning summaries and progress traces |
+| `<osx-plan>` | Ordered agent steps with pending, active, done, failed, and skipped states |
+| `<osx-artifact>` | Generated file, document, and code output with copy, download, open, and version actions |
+| `<osx-markdown>` | Injection-safe, streaming Markdown with code copy, tables, lists, quotes, and links |
+| `<osx-citation>` | Inline citation chip for grounded RAG and search responses |
+| `<osx-source-panel>` | Coordinated source list with selection, domains, and supporting excerpts |
+| `<osx-tool-call>` | Expandable queued, running, successful, and failed tool activity |
+| `<osx-diff-viewer>` | Unified and split code review with line numbers, statistics, and layout controls |
+| `<osx-terminal>` | Command output with lifecycle state, rerun, interrupt, and clear actions |
+| `<osx-file-tree>` | Filterable repository hierarchy with selection and Git status markers |
+| `<osx-alert>` | Persistent information, success, warning, and error feedback |
+| `<osx-toast>` | Transient notifications with placement, timeout, and dismissal control |
+| `<osx-shimmer>` | Flexible reduced-motion-aware loading placeholder |
+| `<osx-skeleton>` | Text, profile, and card loading compositions |
+| `<osx-spinner>` | Compact reduced-motion-aware indeterminate activity feedback |
+| `<osx-icon>` | Curated Lucide SVG iconography with consistent sizing and accessible labels |
+| `<osx-icon-button>` | Accessible icon-only actions with standardized hit areas and states |
+| `<osx-tooltip>` | Supplemental hover and focus hints for compact controls |
+| `<osx-popover>` | Anchored contextual content with explicit dismissal |
+| `<osx-menu>` | Keyboard-oriented collections of application commands |
+| `<osx-menu-item>` | Action and checkbox menu rows with optional shortcuts |
+| `<osx-tabs>` | Related content panels with roving keyboard selection |
+| `<osx-dialog>` | Centered modal with focus management and controlled actions |
+| `<osx-ecosystem-card>` | Transparent first-party product discovery with provenance and host-owned tracking hooks |
+| `<osx-empty-state>` | Zero-data guidance with an optional recovery action |
+| `<osx-badge>` | Compact status, count, and category labels |
+| `<osx-avatar>` | Initials, image fallback, and presence status |
+| `<osx-heading>` | Semantic display, title, section, and label typography |
+| `<osx-copy>` | Body copy with readable measures, sizes, tones, and emphasis |
+| `<osx-link>` | Native navigation with external, download, and disabled states |
+| `<osx-button>` | Default, primary, danger, loading, compact, and Lucide icon actions |
+| `<osx-checkbox>` | Checked, mixed, disabled, and slotted-label states |
+| `<osx-radio-group>` | Native single-choice forms with structured options, validation, and optional choice cards |
+| `<osx-toggle>` | Immediate on/off settings with native switch semantics |
+| `<osx-window>` | Window chrome, controls, toolbar and footer slots |
+| `<osx-toolbar>` | Three-region application toolbar |
+| `<osx-segmented-control>` | Accessible single-selection view control |
+| `<osx-select>` | Native selection with structured options, validation, and OS X pop-up styling |
+| `<osx-sheet>` | Window-attached confirmation and task dialog |
+| `<osx-source-list>` | Finder-style application navigation |
+| `<osx-split-view>` | Primary-detail horizontal or vertical layout |
+| `<osx-status-bar>` | Readiness, activity, and connection state |
+| `<osx-table>` | Responsive native data table with sortable columns and safe narrow-screen scrolling |
+| `<osx-data-table>` | Searchable, sortable, selectable, paginated application data with client and server orchestration modes |
+| `<osx-textarea>` | Labeled multi-line input with validation and controlled resize behavior |
+| `<osx-text-field>` | Labeled text, email, password, search, telephone, and URL inputs with validation and optional Lucide icons |
+| `<osx-progress>` | Determinate and indeterminate progress |
+
+## Events
+
+Custom-element events expose Vue event arguments in `event.detail`. Form and selection events bubble through the document, cross shadow boundaries, and update the custom element's public `value` or `checked` property before listeners run.
+
+```js
+document.querySelector("osx-segmented-control")
+  .addEventListener("change", (event) => console.log(event.detail[0]));
+```
+
+`<osx-window>` emits `close`, `minimize`, and `zoom`. `<osx-sheet>` emits `close` and `confirm`. Selection and form components emit `change`; `<osx-text-field>` and `<osx-textarea>` also emit `input`, and `<osx-table>` emits `sort` with the selected key and direction. `<osx-app-shell>` emits `panel-resize` with the panel name and its pixel width so the host can persist a preference. `<osx-data-table>` emits `search`, `sort`, `page-change`, `page-size-change`, `selection-change`, and `row-activate`, allowing its client-side behavior to be replaced by server orchestration without changing the visual contract. `<osx-ecosystem-card>` emits `activate` with its product name, destination, and optional tracking ID. It never sends analytics or makes network requests itself; the host application decides whether and how to measure discovery.
+
+## Native forms
+
+`<osx-text-field>`, `<osx-textarea>`, `<osx-select>`, `<osx-radio-group>`, `<osx-checkbox>`, and `<osx-toggle>` are form-associated custom elements. Named controls contribute to `FormData`, respect `required` and disabled fieldsets, expose standard validity methods, and restore their initial state on `form.reset()`. Checkbox and toggle values default to `on`. Use `<osx-button type="submit">` or `<osx-button type="reset">` for outer-form actions; the default type is `button`.
+
+```html
+<form id="preferences">
+  <osx-text-field name="project" label="Project" required></osx-text-field>
+  <osx-checkbox name="telemetry" label="Share diagnostics"></osx-checkbox>
+  <osx-button type="submit" variant="primary">Save</osx-button>
+</form>
+```
+
+Agent events preserve backend neutrality. `<osx-agent-composer>` emits `input`, `submit`, and `stop`; `<osx-agent-approval>` emits `approve` and `reject`; `<osx-thinking>` emits `toggle`; `<osx-artifact>` emits `copy`, `download`, and `open`; `<osx-markdown>` emits `copy`; and citations coordinate through `activate` and `select`. `<osx-diff-viewer>` emits `view-change` and `copy`; `<osx-terminal>` emits `rerun`, `interrupt`, and `clear`; `<osx-file-tree>` emits `select` and `toggle`. `<osx-alert>` emits `dismiss`; `<osx-toast>` emits `dismiss` with either `manual` or `timeout` as its reason. Your application owns model calls, tool execution, permission policy, persistence, and streaming transport.
+
+## Icons
+
+`<osx-icon>` is the library's shared icon contract. It exposes a curated 56-icon vocabulary from the maintained `@lucide/vue` package, using direct SVG component imports instead of an icon font. Icons share Lucide's consistent stroke geometry and support custom size, stroke width, and accessible labels. Decorative icons are hidden from assistive technology; pass `label` when an icon carries meaning.
+
+Use `<osx-icon-button>` for icon-only actions. It requires an accessible label and standardizes small, medium, and large hit areas; pair unfamiliar actions with `<osx-tooltip>` for visible guidance. Standard `<osx-button>` actions accept `icon` and `icon-position` when an icon should reinforce a visible text label.
+
+## Agent workspace
+
+The agent components are deliberately composable. The shell manages layout; it does not execute tools or call a model.
+
+```html
+<osx-app-shell app-title="Project Agent" inspector-open resizable>
+  <nav slot="sidebar">...</nav>
+  <osx-agent-message message-role="assistant" author="Agent" model="Your model">
+    <p>I inspected the change and verified the focused test.</p>
+  </osx-agent-message>
+  <osx-agent-composer slot="composer" model="Provider · Model"></osx-agent-composer>
+  <aside slot="inspector">...</aside>
+  <osx-status-bar slot="status" label="Ready"></osx-status-bar>
+</osx-app-shell>
+```
+
+The shell fills a definite-height container and keeps oversized workspace content inside its scroll regions. Define the application height chain when the shell should occupy the viewport:
+
+```css
+html,
+body,
+#app {
+  height: 100%;
+}
+
+osx-app-shell {
+  height: 100%;
+}
+```
+
+Use `height: 100dvh` on `<osx-app-shell>` when it is the viewport root. The component retains a 520px minimum height; on narrow screens its workspace remains independently scrollable, and the shell can scroll when the stacked regions exceed the assigned height.
+
+## Framework starters
+
+The showcase includes shareable, URL-addressable starters for HTML, Vue, React, and Svelte. Choose a framework in the [Snippet Lab](https://osx-components.vercel.app/#snippets), copy the generated component shell, or share a URL such as `?framework=react#snippets`.
+
+## Component explorer
+
+The [Component Explorer](https://osx-components.vercel.app/components) is a Storybook-style second entry point with searchable, deep-linkable, live examples of every published element. It is built from the same package entry point consumers install, so the stories exercise the actual Custom Elements API rather than a private Vue-only layer.
+
+## Development
+
+```bash
+npm install
+npm run dev
+npm run check
+npm run build:site
+```
+
+The showcase deliberately consumes the library as native HTML elements. That keeps framework independence honest. `npm run build` creates the publishable component package in `dist`; `npm run build:site` creates the deployable showcase in `site-dist`.
+
+## Direction
+
+The next useful components are breadcrumbs, date pickers, command palettes, disclosure groups, context meters, and inspector panels. Visual fidelity matters, but accessibility and predictable web behavior win when the two conflict.
+
+## License
+
+MIT. “Mac,” “Mac OS,” and “OS X” are trademarks of Apple Inc. This independent project is not affiliated with or endorsed by Apple.

package/bin/osx-components.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+import { existsSync } from "node:fs";
+import { cp, mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const skillName = "build-with-osx-components";
+const skillSource = join(packageRoot, "skills", skillName);
+
+function help() {
+  console.log(`OSX Components agent installer
+
+Usage:
+  osx-components agent install [options]
+
+Options:
+  --target <agents|codex|claude|opencode|cursor|auto|all>
+  --scope <project|user>       Default: project
+  --cwd <path>                 Default: current directory
+  --force                      Replace an existing installed copy
+  --dry-run                    Print destinations without writing
+  --help                       Show this help
+
+Examples:
+  npx @vraxis/osx-components agent install
+  npx @vraxis/osx-components agent install --target claude --scope user
+  npx @vraxis/osx-components agent install --target all --force
+`);
+}
+
+async function exists(path) {
+  try { await stat(path); return true; }
+  catch { return false; }
+}
+
+function option(args, name, fallback) {
+  const index = args.indexOf(name);
+  return index >= 0 ? args[index + 1] : fallback;
+}
+
+function targetsFor(requested, cwd) {
+  const supported = ["agents", "codex", "claude", "opencode", "cursor"];
+  if (requested === "all") return supported;
+  if (requested !== "auto") return [requested];
+  const detected = supported.filter((target) => target !== "agents" && existsSync(join(cwd, `.${target}`)));
+  return detected.length ? detected : ["agents"];
+}
+
+function destinationFor(target, scope, cwd) {
+  const project = {
+    agents: join(cwd, ".agents", "skills", skillName),
+    codex: join(cwd, ".codex", "skills", skillName),
+    claude: join(cwd, ".claude", "skills", skillName),
+    opencode: join(cwd, ".opencode", "skills", skillName),
+    cursor: join(cwd, ".cursor", "rules", "osx-components.mdc"),
+  };
+  const user = {
+    agents: join(homedir(), ".agents", "skills", skillName),
+    codex: join(homedir(), ".codex", "skills", skillName),
+    claude: join(homedir(), ".claude", "skills", skillName),
+    opencode: join(homedir(), ".config", "opencode", "skills", skillName),
+  };
+  if (scope === "user" && target === "cursor") throw new Error("Cursor file-based rules are project scoped. Use --scope project.");
+  return (scope === "user" ? user : project)[target];
+}
+
+async function cursorRule() {
+  const skill = await readFile(join(skillSource, "SKILL.md"), "utf8");
+  const body = skill.replace(/^---[\s\S]*?---\s*/, "").replaceAll(/\[([^\]]+)\]\(references\/[^)]+\)/g, "$1 (bundled below)");
+  const references = ["component-selection.md", "framework-usage.md", "composition-patterns.md", "quality-standard.md"];
+  const bundled = await Promise.all(references.map(async (name) => `\n\n---\n\n${await readFile(join(skillSource, "references", name), "utf8")}`));
+  return `---\ndescription: Build and review interfaces with the osx-components design system\nglobs:\nalwaysApply: false\n---\n\n<!-- Generated from the osx-components ${skillName} skill. -->\n\n${body.trim()}${bundled.join("")}\n`;
+}
+
+async function install(target, scope, cwd, force, dryRun) {
+  const destination = destinationFor(target, scope, cwd);
+  if (dryRun) return { target, destination, state: "planned" };
+  if (await exists(destination)) {
+    if (!force) throw new Error(`${destination} already exists. Re-run with --force to update it.`);
+    await rm(destination, { recursive: true, force: true });
+  }
+  await mkdir(dirname(destination), { recursive: true });
+  if (target === "cursor") await writeFile(destination, await cursorRule(), "utf8");
+  else await cp(skillSource, destination, { recursive: true });
+  return { target, destination, state: "installed" };
+}
+
+const args = process.argv.slice(2);
+if (args.includes("--help") || args.length === 0) { help(); process.exit(0); }
+if (args[0] !== "agent" || args[1] !== "install") { help(); process.exitCode = 1; }
+else {
+  const target = option(args, "--target", "agents");
+  const scope = option(args, "--scope", "project");
+  const cwd = resolve(option(args, "--cwd", process.cwd()));
+  const supported = new Set(["agents", "codex", "claude", "opencode", "cursor", "auto", "all"]);
+  if (!supported.has(target)) throw new Error(`Unsupported target: ${target}`);
+  if (!new Set(["project", "user"]).has(scope)) throw new Error(`Unsupported scope: ${scope}`);
+  const results = [];
+  for (const item of targetsFor(target, cwd)) results.push(await install(item, scope, cwd, args.includes("--force"), args.includes("--dry-run")));
+  for (const result of results) console.log(`${result.state === "planned" ? "Would install" : "Installed"} ${result.target}: ${result.destination}`);
+}

package/dist/osx-components.css

@@ -0,0 +1 @@
+:root,[data-osx-theme=aqua]{--osx-font: "Lucida Grande", "Helvetica Neue", Arial, sans-serif;--osx-text: #243b4a;--osx-muted: #526671;--osx-border: #8d9ba5;--osx-border-soft: #c6d0d6;--osx-surface: #f4f7f9;--osx-surface-raised: #ffffff;--osx-surface-sunken: #e4eaee;--osx-title-start: #eef3f6;--osx-title-end: #bdc8cf;--osx-accent: #006da8;--osx-accent-light: #75c8f5;--osx-success: #2f9951;--osx-warning: #c9821e;--osx-danger: #c74d47;--osx-focus: rgba(35, 145, 218, .32);--osx-shadow: 0 14px 38px rgba(31, 49, 61, .24), 0 2px 7px rgba(31, 49, 61, .2);--osx-highlight: rgba(255, 255, 255, .86);color-scheme:light}[data-osx-theme=graphite]{--osx-accent: #506978;--osx-accent-light: #a7bac6;--osx-focus: rgba(91, 121, 140, .32)}[data-osx-theme=panther]{--osx-text: #e5edf2;--osx-muted: #93a3ad;--osx-border: #52616b;--osx-border-soft: #354149;--osx-surface: #1b2328;--osx-surface-raised: #273138;--osx-surface-sunken: #11181c;--osx-title-start: #465159;--osx-title-end: #293138;--osx-accent: #1594d6;--osx-accent-light: #54bced;--osx-success: #42ae67;--osx-warning: #dfa23b;--osx-danger: #e16059;--osx-focus: rgba(59, 177, 233, .38);--osx-shadow: 0 16px 42px rgba(0, 0, 0, .52), 0 2px 7px rgba(0, 0, 0, .46);--osx-highlight: rgba(255, 255, 255, .13);color-scheme:dark}