@rak200/ui 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) rak200
+
+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,54 @@
+# @rak200/ui
+
+[![CI](https://github.com/rak200/ui/actions/workflows/ci.yml/badge.svg)](https://github.com/rak200/ui/actions/workflows/ci.yml)
+[![node](https://img.shields.io/badge/node-%3E%3D22-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org/)
+[![Mutation testing](https://img.shields.io/badge/Stryker-MSI%20100%25-brightgreen)](stryker.config.js)
+[![Code style](https://img.shields.io/badge/code%20style-Prettier-blue?logo=prettier&logoColor=white)](prettier.config.js)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![SemVer](https://img.shields.io/badge/semver-2.0.0-blue)](https://semver.org/spec/v2.0.0.html)
+
+Host-agnostic custom-element UI components for the rak200 ecosystem.
+
+They are **custom elements**, so they work in any page and any framework — or none. That is the
+whole point: a component welded to one framework is not reusable outside it, and this kit exists to
+be reused. Built with [Lit](https://lit.dev) for a thin runtime with no build step required of the
+host. See [RFC 0016](https://github.com/rak200/devr/blob/master/docs/proposals/0016-ui-component-library.md)
+for how that was decided and what was rejected.
+
+## Install
+
+```bash
+npm install @rak200/ui
+```
+
+## Use
+
+```html
+<script type="module">
+  import '@rak200/ui';
+</script>
+
+<rak-button>Save</rak-button>
+<rak-button variant="secondary">Cancel</rak-button>
+<rak-button disabled>Unavailable</rak-button>
+```
+
+Every visual decision is a CSS custom property, so a host restyles the kit without forking it:
+
+```css
+:root {
+  --rak-color-accent: rebeccapurple;
+  --rak-radius: 0;
+}
+```
+
+## Documentation
+
+The reference lives in [docs/](docs/README.md) — one page per unit.
+
+## Status
+
+**v0.** One component and the token layer, built to the ecosystem's full quality bar rather than
+sketched: type-checked at the strictest available setting, formatted, tested in a real browser,
+100% coverage and **100% mutation score**, scanned, and every public symbol documented. The v0
+surface in RFC 0016 grows from here — see [ROADMAP.md](ROADMAP.md).

package/dist/button.d.ts

@@ -0,0 +1,49 @@
+import { LitElement, type TemplateResult } from 'lit';
+/** How much visual weight a button carries. */
+export type ButtonVariant = 'primary' | 'secondary';
+/**
+ * A button.
+ *
+ * It delegates to a real `<button>` in its shadow root rather than reimplementing one,
+ * which is what makes the keyboard behaviour, the accessible name and the disabled
+ * semantics the platform's job instead of this file's. No state machine is involved
+ * because a button has no state to model — Zag arrives with the first component that
+ * does.
+ *
+ * @example
+ * ```html
+ * <rak-button variant="primary">Save</rak-button>
+ * ```
+ */
+export declare class RakButton extends LitElement {
+    static readonly styles: import("lit").CSSResult;
+    static readonly properties: {
+        variant: {
+            type: StringConstructor;
+            reflect: boolean;
+        };
+        disabled: {
+            type: BooleanConstructor;
+            reflect: boolean;
+        };
+    };
+    /**
+     * How much visual weight the button carries.
+     *
+     * A plain field, not the `accessor` keyword: `accessor` is an auto-accessor, the
+     * browser the suite runs in does not implement it, and the transform leaves it in
+     * place — the module then fails to parse. The classic Lit pattern, a `static
+     * properties` map beside plain fields with `useDefineForClassFields: false`, needs
+     * neither the keyword nor decorators.
+     */
+    variant: ButtonVariant;
+    /** Whether the button rejects interaction. Reflected, so CSS can select on it. */
+    disabled: boolean;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'rak-button': RakButton;
+    }
+}
+//# sourceMappingURL=button.d.ts.map

package/dist/button.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"button.d.ts","sourceRoot":"","sources":["../src/button.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAa,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AAEjE,+CAA+C;AAC/C,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,WAAW,CAAC;AAEpD;;;;;;;;;;;;;GAaG;AACH,qBAAa,SAAU,SAAQ,UAAU;IACrC,gBAAyB,MAAM,0BAoC7B;IAEF,gBAAyB,UAAU;;;;;;;;;MAGjC;IAEF;;;;;;;;OAQG;IACH,OAAO,EAAE,aAAa,CAAa;IAEnC,kFAAkF;IAClF,QAAQ,UAAS;IAER,MAAM,IAAI,cAAc;CAOpC;AAQD,OAAO,CAAC,MAAM,CAAC;IACX,UAAU,qBAAqB;QAC3B,YAAY,EAAE,SAAS,CAAC;KAC3B;CACJ"}

package/dist/button.js

@@ -0,0 +1,86 @@
+import { LitElement, css, html } from 'lit';
+/**
+ * A button.
+ *
+ * It delegates to a real `<button>` in its shadow root rather than reimplementing one,
+ * which is what makes the keyboard behaviour, the accessible name and the disabled
+ * semantics the platform's job instead of this file's. No state machine is involved
+ * because a button has no state to model — Zag arrives with the first component that
+ * does.
+ *
+ * @example
+ * ```html
+ * <rak-button variant="primary">Save</rak-button>
+ * ```
+ */
+export class RakButton extends LitElement {
+    constructor() {
+        super(...arguments);
+        /**
+         * How much visual weight the button carries.
+         *
+         * A plain field, not the `accessor` keyword: `accessor` is an auto-accessor, the
+         * browser the suite runs in does not implement it, and the transform leaves it in
+         * place — the module then fails to parse. The classic Lit pattern, a `static
+         * properties` map beside plain fields with `useDefineForClassFields: false`, needs
+         * neither the keyword nor decorators.
+         */
+        this.variant = 'primary';
+        /** Whether the button rejects interaction. Reflected, so CSS can select on it. */
+        this.disabled = false;
+    }
+    static { this.styles = css `
+        :host {
+            display: inline-block;
+        }
+
+        button {
+            font: inherit;
+            font-family: var(--rak-font, system-ui, sans-serif);
+            border: 1px solid transparent;
+            border-radius: var(--rak-radius, 0.375rem);
+            padding: var(--rak-space, 0.5rem) calc(var(--rak-space, 0.5rem) * 2);
+            cursor: pointer;
+        }
+
+        button:disabled {
+            cursor: not-allowed;
+            opacity: 0.5;
+        }
+
+        /* A visible focus ring is not decoration: removing it is the single most common
+       way a component stops being usable by keyboard. */
+        button:focus-visible {
+            outline: 2px solid var(--rak-color-focus, #f59e0b);
+            outline-offset: 2px;
+        }
+
+        button.primary {
+            background: var(--rak-color-accent, #2563eb);
+            color: var(--rak-color-accent-contrast, #ffffff);
+        }
+
+        button.secondary {
+            background: var(--rak-color-surface, #ffffff);
+            color: var(--rak-color-text, #1f2937);
+            border-color: currentcolor;
+        }
+    `; }
+    static { this.properties = {
+        variant: { type: String, reflect: true },
+        disabled: { type: Boolean, reflect: true },
+    }; }
+    render() {
+        return html `
+            <button class=${this.variant} ?disabled=${this.disabled} part="button">
+                <slot></slot>
+            </button>
+        `;
+    }
+}
+// Stryker disable next-line StringLiteral: the registration runs once, at import,
+// inside the warm process Stryker switches mutants in — so by the time a mutant on this
+// line is active the element is already defined under the original name, and no test can
+// observe the change. Outside the runner's reach, not an equivalent mutant.
+customElements.define('rak-button', RakButton);
+//# sourceMappingURL=button.js.map

package/dist/button.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"button.js","sourceRoot":"","sources":["../src/button.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,IAAI,EAAuB,MAAM,KAAK,CAAC;AAKjE;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,SAAU,SAAQ,UAAU;IAAzC;;QA4CI;;;;;;;;WAQG;QACH,YAAO,GAAkB,SAAS,CAAC;QAEnC,kFAAkF;QAClF,aAAQ,GAAG,KAAK,CAAC;IASrB,CAAC;aAhE4B,WAAM,GAAG,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAoCpC,AApC8B,CAoC7B;aAEuB,eAAU,GAAG;QAClC,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE;QACxC,QAAQ,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE;KAC7C,AAHkC,CAGjC;IAgBO,MAAM;QACX,OAAO,IAAI,CAAA;4BACS,IAAI,CAAC,OAAO,cAAc,IAAI,CAAC,QAAQ;;;SAG1D,CAAC;IACN,CAAC;;AAGL,kFAAkF;AAClF,wFAAwF;AACxF,yFAAyF;AACzF,4EAA4E;AAC5E,cAAc,CAAC,MAAM,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { RakButton, type ButtonVariant } from './button.js';
+export { tokens, defaults, tokenStyleSheet, type Token } from './tokens.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,EAAE,KAAK,KAAK,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { RakButton } from './button.js';
+export { tokens, defaults, tokenStyleSheet } from './tokens.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAsB,MAAM,aAAa,CAAC;AAC5D,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,EAAc,MAAM,aAAa,CAAC"}

package/dist/tokens.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Design tokens — the single source of truth for the visual language.
+ *
+ * They exist from day one because they are the only thing that reaches every target the
+ * roadmap has: the web components below consume them as CSS custom properties, and a
+ * native shell (RFC 0016, M4) can read the same values without the components. A token
+ * added later is a token some target already hardcoded.
+ *
+ * Every token is a CSS custom property under `--rak-`, so a host overrides one by
+ * setting it anywhere above the component — no build step, no theme object, no fork.
+ */
+/** The token names this package defines, as they appear in CSS. */
+export declare const tokens: readonly ["--rak-color-accent", "--rak-color-accent-contrast", "--rak-color-surface", "--rak-color-text", "--rak-color-focus", "--rak-radius", "--rak-space", "--rak-font"];
+/** A CSS custom property this package defines. */
+export type Token = (typeof tokens)[number];
+/**
+ * The default value of every token, applied at `:root` by {@link tokenStyleSheet}.
+ *
+ * These are deliberately plain and low-contrast-safe rather than branded: a design
+ * system's defaults are what a host sees before it has decided anything.
+ */
+export declare const defaults: Readonly<Record<Token, string>>;
+/**
+ * The token defaults as a CSS rule, for a host that wants them without importing a
+ * component. Returns the text of a `:root` block; a host inserts it however it prefers.
+ */
+export declare function tokenStyleSheet(): string;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,mEAAmE;AACnE,eAAO,MAAM,MAAM,6KAST,CAAC;AAEX,kDAAkD;AAClD,MAAM,MAAM,KAAK,GAAG,CAAC,OAAO,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5C;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CASpD,CAAC;AAEF;;;GAGG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAIxC"}

package/dist/tokens.js

@@ -0,0 +1,47 @@
+/**
+ * Design tokens — the single source of truth for the visual language.
+ *
+ * They exist from day one because they are the only thing that reaches every target the
+ * roadmap has: the web components below consume them as CSS custom properties, and a
+ * native shell (RFC 0016, M4) can read the same values without the components. A token
+ * added later is a token some target already hardcoded.
+ *
+ * Every token is a CSS custom property under `--rak-`, so a host overrides one by
+ * setting it anywhere above the component — no build step, no theme object, no fork.
+ */
+/** The token names this package defines, as they appear in CSS. */
+export const tokens = [
+    '--rak-color-accent',
+    '--rak-color-accent-contrast',
+    '--rak-color-surface',
+    '--rak-color-text',
+    '--rak-color-focus',
+    '--rak-radius',
+    '--rak-space',
+    '--rak-font',
+];
+/**
+ * The default value of every token, applied at `:root` by {@link tokenStyleSheet}.
+ *
+ * These are deliberately plain and low-contrast-safe rather than branded: a design
+ * system's defaults are what a host sees before it has decided anything.
+ */
+export const defaults = {
+    '--rak-color-accent': '#2563eb',
+    '--rak-color-accent-contrast': '#ffffff',
+    '--rak-color-surface': '#ffffff',
+    '--rak-color-text': '#1f2937',
+    '--rak-color-focus': '#f59e0b',
+    '--rak-radius': '0.375rem',
+    '--rak-space': '0.5rem',
+    '--rak-font': 'system-ui, sans-serif',
+};
+/**
+ * The token defaults as a CSS rule, for a host that wants them without importing a
+ * component. Returns the text of a `:root` block; a host inserts it however it prefers.
+ */
+export function tokenStyleSheet() {
+    const body = tokens.map((token) => `  ${token}: ${defaults[token]};`).join('\n');
+    return `:root {\n${body}\n}`;
+}
+//# sourceMappingURL=tokens.js.map

package/dist/tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,mEAAmE;AACnE,MAAM,CAAC,MAAM,MAAM,GAAG;IAClB,oBAAoB;IACpB,6BAA6B;IAC7B,qBAAqB;IACrB,kBAAkB;IAClB,mBAAmB;IACnB,cAAc;IACd,aAAa;IACb,YAAY;CACN,CAAC;AAKX;;;;;GAKG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAoC;IACrD,oBAAoB,EAAE,SAAS;IAC/B,6BAA6B,EAAE,SAAS;IACxC,qBAAqB,EAAE,SAAS;IAChC,kBAAkB,EAAE,SAAS;IAC7B,mBAAmB,EAAE,SAAS;IAC9B,cAAc,EAAE,UAAU;IAC1B,aAAa,EAAE,QAAQ;IACvB,YAAY,EAAE,uBAAuB;CACxC,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,eAAe;IAC3B,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,KAAK,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEjF,OAAO,YAAY,IAAI,KAAK,CAAC;AACjC,CAAC"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@rak200/ui",
+  "version": "0.1.0",
+  "description": "Host-agnostic custom-element UI components for the rak200 ecosystem",
+  "license": "MIT",
+  "author": "rak200 <rak.ricardo@windowslive.com>",
+  "homepage": "https://github.com/rak200/ui",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rak200/ui.git"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": [
+    "./dist/*.js"
+  ],
+  "scripts": {
+    "validate": "npm run build && publint --strict",
+    "lint": "prettier --check .",
+    "fix": "prettier --write . && eslint --fix .",
+    "analyse": "tsc --noEmit && eslint .",
+    "test": "vitest run",
+    "coverage": "coverage-floor",
+    "scan": "semgrep scan --config=p/typescript --severity=ERROR --sarif -o semgrep.sarif",
+    "mutation": "stryker run",
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "dependencies": {
+    "lit": "^3.3.3"
+  },
+  "devDependencies": {
+    "@rak200/coding-standard-ts": "github:rak200/coding-standard-ts#0.4.0",
+    "@types/node": "^26.1.2",
+    "@vitest/browser-playwright": "^4.1.10"
+  }
+}