@vraxis/osx-components 0.11.3

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@vraxis/osx-components",
+  "version": "0.11.3",
+  "description": "OS X-inspired web components authored with Vue.",
+  "type": "module",
+  "sideEffects": [
+    "*.css"
+  ],
+  "files": [
+    "bin",
+    "dist",
+    "skills",
+    "types",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./dist/osx-components.js",
+  "module": "./dist/osx-components.js",
+  "types": "./types/index.d.ts",
+  "bin": {
+    "osx-components": "bin/osx-components.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "import": "./dist/osx-components.js"
+    },
+    "./theme.css": "./dist/osx-components.css",
+    "./skill": "./skills/build-with-osx-components/SKILL.md"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "vue-tsc -b && vite build",
+    "build:site": "vite build --config vite.site.config.ts",
+    "test": "node --test test/*.test.mjs",
+    "test:consumers": "npm run build && node test/packed-consumer.mjs && node test/framework-builds.mjs",
+    "test:browser": "playwright test",
+    "test:visual:update": "playwright test --update-snapshots",
+    "test:quality": "npm run check && npm run test:consumers && npm run test:browser",
+    "check": "npm run test && npm run build",
+    "preview": "vite preview",
+    "preview:site": "vite preview --config vite.site.config.ts",
+    "audit:osx": "node skills/build-with-osx-components/scripts/audit-osx-ui.mjs ."
+  },
+  "keywords": [
+    "web-components",
+    "vue",
+    "macos",
+    "osx",
+    "aqua",
+    "design-system"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Vequan23/osx-components.git"
+  },
+  "homepage": "https://github.com/Vequan23/osx-components#readme",
+  "bugs": "https://github.com/Vequan23/osx-components/issues",
+  "dependencies": {
+    "@lucide/vue": "^1.33.0",
+    "vue": "^3.5.21"
+  },
+  "devDependencies": {
+    "@axe-core/playwright": "^4.13.0",
+    "@playwright/test": "^1.62.1",
+    "@sveltejs/vite-plugin-svelte": "^6.2.4",
+    "@types/node": "^26.2.0",
+    "@vitejs/plugin-react": "^5.2.0",
+    "@vitejs/plugin-vue": "^6.0.1",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "svelte": "^5.56.10",
+    "typescript": "^5.9.3",
+    "vite": "^7.1.3",
+    "vue-tsc": "^3.0.8"
+  }
+}

package/skills/build-with-osx-components/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: build-with-osx-components
+description: Build, refactor, or review web interfaces that use the @vraxis/osx-components package and its OS X-inspired custom elements. Use for application shells, dashboards, settings, data tables, agent workbenches, feedback, typography, theming, icons, responsive layouts, accessibility, or migrations from bespoke controls to OSX Components in HTML, Vue, React, Svelte, Astro, and other web projects.
+---
+
+# Build with OSX Components
+
+Build cohesive interfaces from the published primitives before creating custom UI. Treat the package as a framework-neutral Custom Elements design system: the host owns application state, data, routing, model calls, tool execution, persistence, and analytics.
+
+## Workflow
+
+1. Inspect the host project before editing.
+   - Identify its framework, package manager, entry point, theme root, and existing `@vraxis/osx-components` version.
+   - Search for existing OSX Components usage and preserve established composition patterns.
+   - Do not install, upgrade, or replace dependencies unless the task authorizes it.
+2. Choose primitives before writing markup.
+   - Read [references/component-selection.md](references/component-selection.md) when selecting or combining components.
+   - Inspect `node_modules/@vraxis/osx-components/types/index.d.ts` for the exact installed API. In the library repository, inspect `types/index.d.ts` and `demo/component-docs.ts`.
+   - Never invent a component, prop, slot, event, token, or icon name.
+3. Integrate once at the application boundary.
+   - Import `@vraxis/osx-components/theme.css` once.
+   - Call `registerOsxComponents()` once in the client entry point.
+   - Set `data-osx-theme="aqua"`, `graphite`, or `panther` on a stable ancestor.
+   - Read [references/framework-usage.md](references/framework-usage.md) only for the active framework.
+4. Compose the interface.
+   - Read [references/composition-patterns.md](references/composition-patterns.md) for shells, agent workspaces, settings, repository tools, and data-heavy views.
+   - Prefer component props and slots over shadow-root overrides.
+   - Use `--osx-*` tokens for intentional product-level customization.
+   - Keep application behavior outside the components and respond to emitted custom events.
+5. Verify the finished experience.
+   - Read [references/quality-standard.md](references/quality-standard.md).
+   - Run the host project's typecheck, tests, and production build.
+   - Run `node <skill-directory>/scripts/audit-osx-ui.mjs <project-root>` and address errors. Use `--strict` when warnings should block completion.
+   - Exercise keyboard behavior and inspect desktop and mobile layouts in a real browser.
+
+## Non-negotiable rules
+
+- Keep rendered text at 12px or larger.
+- Use `<osx-icon>` or component icon props with a supported Lucide name. Do not use emoji, Unicode symbols, or improvised text glyphs as interface icons.
+- Use `<osx-icon-button label="…">` for icon-only actions. Pair unfamiliar compact actions with `<osx-tooltip>`.
+- Prefer native-semantic components over clickable generic containers.
+- Preserve visible focus, keyboard operation, accessible names, textual status, and reduced-motion behavior.
+- Do not convey state with color alone.
+- Do not make Apple affiliation claims or copy Apple assets. Reuse the interaction language and token system only.
+- Do not make components perform hidden network requests, analytics, model calls, or privileged actions. Keep those decisions with the host.
+- Do not expose private reasoning as chain-of-thought. Use `<osx-thinking>` for a concise model-provided progress or reasoning summary.
+- Do not create a new primitive merely to reproduce a published component. Compose existing primitives first.
+
+## Event and data boundary
+
+Custom-element events expose Vue event arguments in `event.detail`. Read the first emitted argument with `event.detail[0]` unless the installed type or documentation says otherwise.
+
+Assign arrays and objects as DOM properties when possible. JSON attributes remain useful for static HTML examples, but property assignment avoids escaping errors and preserves value types.
+
+## Completion report
+
+State which OSX Components were used, any intentional custom CSS or missing primitive, the theme verified, and the checks run. Mention unresolved accessibility, mobile, or API uncertainty explicitly.

package/skills/build-with-osx-components/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Build with OSX Components"
+  short_description: "Build consistent interfaces with OSX Components"
+  default_prompt: "Use $build-with-osx-components to build this interface from accessible OSX Components primitives."

package/skills/build-with-osx-components/references/component-selection.md

@@ -0,0 +1,72 @@
+# Component selection
+
+Use this guide to choose a primitive. Inspect the installed `types/index.d.ts` before relying on exact props or events.
+
+## Application structure
+
+- `osx-app-shell`: full workspace with toolbar, sidebar, main content, composer, inspector, and status areas; opt into accessible side-panel resizing with `resizable`.
+- `osx-window`: bounded window chrome for demos, settings, and focused surfaces.
+- `osx-toolbar`: leading, center, and trailing application actions.
+- `osx-source-list`: Finder-style navigation.
+- `osx-split-view`: primary-detail or stacked responsive panes.
+- `osx-status-bar`: concise connection or activity context.
+- `osx-tabs`: switch among related panels without navigation.
+
+## Actions and inputs
+
+- `osx-button`: visible text action, optionally reinforced by a Lucide icon.
+- `osx-icon-button`: compact icon-only action with a required accessible label.
+- `osx-text-field`: labeled single-line text, email, password, search, telephone, or URL input with validation and an optional icon.
+- `osx-textarea`: labeled multi-line input with validation and controlled resize behavior.
+- `osx-select`: native single-choice input with comma-separated labels or structured options.
+- `osx-radio-group`: native single-choice group when every option should stay visible; use its card variant for choices with supporting descriptions.
+- `osx-checkbox`: independent or multi-select choice.
+- `osx-toggle`: immediate on/off setting.
+- `osx-segmented-control`: compact single selection among a few views.
+- `osx-menu` and `osx-menu-item`: keyboard-oriented command collection.
+
+## Data and repository views
+
+- `osx-data-table`: searching, sorting, pagination, selection, loading, row activation, and server orchestration.
+- `osx-table`: lightweight native table when advanced orchestration is unnecessary.
+- `osx-file-tree`: filterable repository hierarchy with Git status.
+- `osx-diff-viewer`: unified or split patch evidence.
+- `osx-terminal`: command, output, state, and bounded execution controls.
+- `osx-progress`: determinate or indeterminate progress with a measurable task.
+
+## Agent interfaces
+
+- `osx-agent-composer`: prompt entry, submission, busy state, model context, and stop action.
+- `osx-agent-message`: user, assistant, system, streaming, and error messages.
+- `osx-agent-run-status`: run-level plan, work, verify, completion, and failure lifecycle.
+- `osx-agent-approval`: explicit human approval for a bounded action.
+- `osx-thinking`: collapsible reasoning summary or progress trace.
+- `osx-plan`: task steps with pending, active, done, failed, and skipped states.
+- `osx-tool-call`: expandable tool activity.
+- `osx-artifact`: generated file, document, or code output.
+- `osx-markdown`: safe streaming Markdown.
+- `osx-citation` and `osx-source-panel`: coordinated grounded sources.
+
+## Feedback and overlays
+
+- `osx-alert`: persistent contextual feedback.
+- `osx-toast`: transient completion or failure notice.
+- `osx-empty-state`: absence of data plus an optional recovery action.
+- `osx-spinner`: compact indeterminate activity.
+- `osx-shimmer` and `osx-skeleton`: layout-preserving loading placeholders.
+- `osx-dialog`: centered modal decision or focused content.
+- `osx-sheet`: window-attached confirmation or task surface.
+- `osx-popover`: anchored contextual content.
+- `osx-tooltip`: supplemental hover and focus hint, never an action's only label.
+
+## Content and identity
+
+- `osx-heading`, `osx-copy`, and `osx-link`: semantic typography and navigation.
+- `osx-icon`: supported Lucide glyph.
+- `osx-avatar`: person or agent identity and presence.
+- `osx-badge`: compact category, count, or status.
+- `osx-ecosystem-card`: transparent first-party ecosystem discovery with host-owned tracking.
+
+## Selection rule
+
+Use the smallest component that owns the needed semantics. Compose multiple primitives for product-specific layouts; create custom CSS only for arrangement and product identity that tokens and slots do not cover.

package/skills/build-with-osx-components/references/composition-patterns.md

@@ -0,0 +1,47 @@
+# Composition patterns
+
+## Product workspace
+
+Use `osx-app-shell` as the layout owner. Put primary navigation in `sidebar`, persistent actions in `toolbar`, contextual detail in `inspector`, creation input in `composer`, and concise state in `status`. Keep page-specific content in the default slot.
+
+Set `resizable` when desktop users benefit from changing the navigation or inspector width. Configure the four pixel bounds for the product's content, listen for `panel-resize`, and let the host persist the preference. Resize handles disappear when the shell stacks on narrow screens.
+
+Do not repeat project identity, model identity, or run status in multiple shell regions. Give each fact one stable home.
+
+## Agent workbench
+
+Compose:
+
+1. `osx-agent-message` for the conversation.
+2. `osx-thinking` for an optional progress summary.
+3. `osx-plan` for explicit task steps.
+4. `osx-tool-call` for bounded actions and inspectable output.
+5. `osx-artifact` or `osx-diff-viewer` for generated work.
+6. `osx-agent-approval` before consequential actions.
+7. `osx-agent-composer` as the persistent input.
+
+Show the response immediately after completion. Keep raw tool traces in activity, not in the primary response body. Never manufacture changes when the agent answered with analysis only.
+
+## Repository comprehension
+
+Use `osx-file-tree` beside `osx-diff-viewer` or an artifact preview. Use a resizable `osx-split-view` when both panes need sustained attention. Put verification output in `osx-terminal`; summarize the result in an alert or status bar rather than duplicating the complete log.
+
+## Settings
+
+Use semantic headings and copy, `osx-text-field` for single-line values, and `osx-textarea` for multi-line content. Use `osx-radio-group` when a mutually exclusive choice should stay visible, `osx-select` when space matters, toggles for immediate binary settings, checkboxes for independent selection, and segmented controls for switching among a few views. Put validation text in the controls' `error` props so it remains programmatically associated. Use a sheet or dialog only when the decision must interrupt the current workflow.
+
+## Data-heavy views
+
+Use `osx-data-table` for application records that need search, sorting, selection, or pagination. Use server mode when the host owns remote filtering and pagination. Keep row actions explicit and avoid making every cell independently clickable.
+
+Pair the table with:
+
+- `osx-empty-state` before data exists.
+- `osx-skeleton` when the table shape is not yet known.
+- the table's loading state when rows are refreshing in place.
+- `osx-alert` for recoverable fetch errors.
+- `osx-toast` for completed mutations.
+
+## Responsive hierarchy
+
+Preserve task order on narrow screens. Collapse secondary navigation and inspectors before compressing primary content. Allow data tables, diffs, terminals, and file trees to scroll within their own bounded regions. Do not reduce typography below 12px to make dense layouts fit.

package/skills/build-with-osx-components/references/framework-usage.md

@@ -0,0 +1,105 @@
+# Framework usage
+
+Register the custom elements once and import the theme once. Avoid invoking `registerOsxComponents()` from every view or component.
+
+## HTML and framework-neutral entry points
+
+```html
+<script type="module">
+  import { registerOsxComponents } from "@vraxis/osx-components";
+  import "@vraxis/osx-components/theme.css";
+  registerOsxComponents();
+</script>
+
+<main data-osx-theme="panther">
+  <osx-button variant="primary" icon="sparkle">Create</osx-button>
+</main>
+```
+
+For structured data, assign the DOM property:
+
+```js
+const table = document.querySelector("osx-data-table");
+table.columns = columns;
+table.rows = rows;
+table.addEventListener("selection-change", (event) => {
+  selectedKeys = event.detail[0];
+});
+```
+
+## Vue
+
+Register from the client entry point:
+
+```ts
+import { registerOsxComponents } from "@vraxis/osx-components";
+import "@vraxis/osx-components/theme.css";
+
+registerOsxComponents();
+```
+
+Vue templates can bind complex properties directly:
+
+```vue
+<osx-data-table
+  :columns="columns"
+  :rows="rows"
+  selectable
+  @selection-change="selected = $event.detail[0]"
+/>
+```
+
+Keep Vue application state outside the custom element. Treat the emitted event as the request to update that state.
+
+## React
+
+Register in a client-only entry module. React 19 handles custom-element properties and events more naturally, but use a ref when a framework or toolchain serializes complex values as attributes.
+
+```tsx
+import { useEffect, useRef } from "react";
+import { registerOsxComponents } from "@vraxis/osx-components";
+import "@vraxis/osx-components/theme.css";
+
+registerOsxComponents();
+
+export function Results({ rows, columns }) {
+  const ref = useRef<HTMLElement & { rows: unknown[]; columns: unknown[] }>(null);
+  useEffect(() => {
+    if (!ref.current) return;
+    ref.current.rows = rows;
+    ref.current.columns = columns;
+  }, [rows, columns]);
+  return <osx-data-table ref={ref} label="Results" />;
+}
+```
+
+Use `addEventListener` with cleanup when React's event typing does not recognize a custom event.
+
+## Svelte
+
+Register once in a client entry or `onMount`, then assign complex properties through a bound element when necessary.
+
+```svelte
+<script lang="ts">
+  import { onMount } from "svelte";
+  import { registerOsxComponents } from "@vraxis/osx-components";
+  import "@vraxis/osx-components/theme.css";
+  onMount(registerOsxComponents);
+</script>
+
+<osx-button variant="primary">Save</osx-button>
+```
+
+## SSR environments
+
+Call `registerOsxComponents()` only in the browser. Use the framework's client entry, client-only boundary, or mount hook so `customElements` is available. Render stable fallback content where hydration behavior matters.
+
+## Theme boundary
+
+Apply one theme to the highest stable product container:
+
+```html
+<div data-osx-theme="aqua">...</div>
+```
+
+Nest a different theme only for a deliberate preview or isolated surface. Prefer `--osx-*` token overrides on the product container over penetrating component shadow roots.

package/skills/build-with-osx-components/references/quality-standard.md

@@ -0,0 +1,44 @@
+# Quality standard
+
+## Visual consistency
+
+- Use one theme boundary and the shared `--osx-*` tokens.
+- Use published spacing, radii, borders, and control sizes before adding custom values.
+- Keep icon geometry consistent through `osx-icon` and supported component icon props.
+- Avoid redundant headers, duplicate status labels, and decorative controls without a task.
+- Keep every rendered font size at 12px or larger.
+
+## Interaction
+
+- Make the primary action obvious and singular within each decision surface.
+- Clear forms after successful submission when retention would cause accidental duplicates.
+- Show immediate feedback for save, submit, copy, connection, and destructive operations.
+- Return focus after dismissing a modal or popover.
+- Ensure loading states explain what is happening and do not trap the user.
+- Keep resizable panels operable by pointer and keyboard, expose their current value, and enforce practical minimum and maximum widths.
+
+## Accessibility
+
+- Use semantic components and landmarks.
+- Provide visible labels for inputs and text labels or accessible names for every action.
+- Associate form hints and validation errors with their native controls, and never rely on a red border alone.
+- Use `osx-icon-button` only with `label`.
+- Keep status textual; color and icons may reinforce it but cannot be the only signal.
+- Verify focus visibility and logical keyboard order.
+- Respect reduced motion and sufficient contrast in Aqua, Graphite, and Panther where applicable.
+
+## Responsive behavior
+
+- Test at a desktop width and at 390px or narrower.
+- Check the document and each dense component for unintended horizontal overflow.
+- Stack toolbars and action groups deliberately rather than squeezing labels.
+- Keep interactive targets usable by touch.
+
+## Technical verification
+
+1. Run the host typecheck and tests.
+2. Run the production build.
+3. Run `audit-osx-ui.mjs` against the changed source tree.
+4. Exercise critical interactions in a browser.
+5. Check the browser console for new errors and warnings.
+6. Report any missing primitive or intentional native control instead of silently duplicating the design system.

package/skills/build-with-osx-components/scripts/audit-osx-ui.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+import { readFile, readdir } from "node:fs/promises";
+import { extname, join, relative, resolve } from "node:path";
+
+const args = process.argv.slice(2);
+const strict = args.includes("--strict");
+const json = args.includes("--json");
+const target = resolve(args.find((arg) => !arg.startsWith("--")) || process.cwd());
+const ignored = new Set(["__tests__", "build", "coverage", "dist", "node_modules", "site-dist", "skills", "test", "tests"]);
+const extensions = new Set([".css", ".html", ".js", ".jsx", ".less", ".mjs", ".sass", ".scss", ".svelte", ".ts", ".tsx", ".vue"]);
+const rawGlyphs = /[✓✔✕✖❯❮▶◀↻⚙⌘◉◆]/u;
+const findings = [];
+
+async function filesIn(directory) {
+  const files = [];
+  for (const entry of await readdir(directory, { withFileTypes: true })) {
+    if (entry.isDirectory() && (entry.name.startsWith(".") || ignored.has(entry.name))) continue;
+    const path = join(directory, entry.name);
+    if (entry.isDirectory()) files.push(...await filesIn(path));
+    else if (extensions.has(extname(entry.name))) files.push(path);
+  }
+  return files;
+}
+
+function lineOf(source, index) {
+  return source.slice(0, index).split("\n").length;
+}
+
+function add(file, source, match, severity, rule, message) {
+  findings.push({ severity, rule, file: relative(target, file), line: lineOf(source, match.index), message });
+}
+
+function isKeyboardShortcutGlyph(source, index) {
+  for (const match of source.matchAll(/\bshortcut\s*=\s*(["'])[\s\S]*?\1/gi)) {
+    if (index >= match.index && index < match.index + match[0].length) return true;
+  }
+  const lineStart = source.lastIndexOf("\n", index) + 1;
+  const lineEnd = source.indexOf("\n", index);
+  if (/\.output\s*=/.test(source.slice(lineStart, lineEnd < 0 ? source.length : lineEnd))) return true;
+  const before = source.slice(0, index);
+  return before.lastIndexOf("<kbd") > before.lastIndexOf("</kbd>");
+}
+
+for (const file of await filesIn(target)) {
+  const source = await readFile(file, "utf8");
+  for (const match of source.matchAll(/font-size\s*:\s*(\d+(?:\.\d+)?)px/gi)) {
+    if (Number(match[1]) < 12) add(file, source, match, "error", "minimum-font-size", `Font size ${match[1]}px is below the 12px minimum.`);
+  }
+  for (const match of source.matchAll(/font\s*:\s*[^;{}]*?(\d+(?:\.\d+)?)px(?:\s*\/[^;{}\s]+)?/gi)) {
+    if (Number(match[1]) < 12) add(file, source, match, "error", "minimum-font-size", `Font shorthand uses ${match[1]}px, below the 12px minimum.`);
+  }
+  for (const match of source.matchAll(/<osx-icon-button\b[^>]*>/gis)) {
+    if (!/(?:^|\s)(?::?label|aria-label)\s*=/.test(match[0])) add(file, source, match, "error", "icon-button-label", "osx-icon-button requires a visible or accessible label prop.");
+  }
+  for (const match of source.matchAll(/<osx-(?:text-field|textarea|select|radio-group)\b[^>]*>/gis)) {
+    if (!/(?:^|\s):?label\s*=/.test(match[0])) add(file, source, match, "error", "form-control-label", "OSX form controls require a visible label prop.");
+  }
+  for (const match of source.matchAll(rawGlyphs.global ? rawGlyphs : new RegExp(rawGlyphs.source, "gu"))) {
+    if (isKeyboardShortcutGlyph(source, match.index)) continue;
+    add(file, source, match, "warning", "raw-interface-glyph", `Replace raw interface glyph ${JSON.stringify(match[0])} with osx-icon or a component icon prop.`);
+  }
+}
+
+const errors = findings.filter((finding) => finding.severity === "error");
+const warnings = findings.filter((finding) => finding.severity === "warning");
+if (json) console.log(JSON.stringify({ target, errors: errors.length, warnings: warnings.length, findings }, null, 2));
+else {
+  for (const finding of findings) console.log(`${finding.severity.toUpperCase()} ${finding.file}:${finding.line} [${finding.rule}] ${finding.message}`);
+  console.log(`OSX Components audit: ${errors.length} error(s), ${warnings.length} warning(s).`);
+}
+process.exitCode = errors.length || (strict && warnings.length) ? 1 : 0;