npm - @ponchia/ui - Versions diffs - 0.2.0 - Mend

@ponchia/ui 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (32) hide show

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 Ponchia
+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 ADDED Viewed

@@ -0,0 +1,160 @@
+# @ponchia/ui
+Shared UI framework for Bronto personal projects. Nothing-inspired:
+monochrome surfaces, a single red accent, dot-matrix display type (Doto),
+flat hairline borders, restrained motion. CSS-first and framework-agnostic.
+## Use
+Install from npm (public, no registry config):
+```bash
+npm i @ponchia/ui
+```
+> Naming: the **npm package** is `@ponchia/ui` (the `@bronto` scope isn't
+> ownable). The **CSS layer** and behavior attributes stay `bronto`
+> (`@layer bronto`, `data-bronto-*`) — that's the design-system namespace,
+> deliberately distinct from the package name. See
+> [`docs/architecture.md`](docs/architecture.md).
+> Not published yet — the only remaining blocker is npm-account side
+> (create the `@ponchia` scope + `NPM_TOKEN`; see [Release](#release)).
+> Until the first publish, depend on a `file:` link to a checkout or a
+> pinned git tag:
+>
+> ```json
+> { "dependencies": { "@ponchia/ui": "file:../bronto-ui" } }
+> ```
+>
+> ```json
+> { "dependencies": { "@ponchia/ui": "github:Ponchia/bronto-ui#semver:^0.2.0" } }
+> ```
+Import the full theme (includes responsive breakpoints):
+```css
+@import '@ponchia/ui/css';
+```
+Or the core bundle if the app manages its own responsive layer:
+```css
+@import '@ponchia/ui/css/core.css';
+```
+The Doto `@font-face` ships in `css/fonts.css` (bundled by both `css` and
+`css/core.css`) with URLs relative to the package, so it resolves through a
+bundler or static serving with no `/fonts` path assumption. To self-host the
+font instead, import everything except `fonts.css` and override `--display` /
+`--dot-font`.
+Everything ships inside a single `@layer bronto`, so any un-layered CSS in
+your app overrides the framework without a specificity fight or `!important`.
+The layer is applied by the `css` and `css/core.css` bundles only —
+importing an individual leaf such as `@ponchia/ui/css/primitives.css`
+directly is **unlayered** (full specificity), which is an intentional
+escape hatch, not the default path.
+Set `data-theme="light"` or `data-theme="dark"` on `<html>`; defaults follow
+`prefers-color-scheme`.
+## Entrypoints
+The CSS is the framework. These optional sibling entrypoints are thin layers
+on top of it — none pull in a UI framework. See
+[`docs/architecture.md`](docs/architecture.md) for the rationale.
+```js
+import tokens, { cssVars, themeColor } from '@ponchia/ui/tokens'; // tokens as data (+ /tokens.json)
+import { ui, cx } from '@ponchia/ui/classes'; // typed class-name recipes
+import { initThemeToggle, dismissible } from '@ponchia/ui/behaviors'; // vanilla, SSR-safe
+```
+```js
+ui.button({ variant: 'ghost' }); // → "ui-button ui-button--ghost"
+themeColor('dark').accent; // → "#ff3b41"
+```
+`behaviors` wires `[data-bronto-theme-toggle]`, `[data-bronto-dismiss]` /
+`[data-bronto-dismissible]`, and `[data-bronto-disclosure]`. Each initializer
+is SSR-safe and returns a cleanup function. `demo/index.html` drives itself
+with these modules, so it is also a live integration test.
+## Layout
+| File             | Contents                                                      |
+| ---------------- | ------------------------------------------------------------- |
+| `tokens.css`     | palette (dual light/dark), spacing, type, motion, dot tokens  |
+| `fonts.css`      | Doto `@font-face` (relative URLs; optional if self-hosting)    |
+| `base.css`       | reset, element defaults, focus, scrollbars                    |
+| `motion.css`     | keyframes + animation utilities + reduced-motion              |
+| `dots.css`       | dot-grid, dot rule, status dot, dot loader/bar, matrix reveal |
+| `primitives.css` | `ui-*` buttons, cards, chips, badges, links, key/value        |
+| `forms.css`      | inputs, select, textarea, search, switch, checkbox            |
+| `table.css`      | `ui-table` dense / comfortable                                |
+| `app.css`        | admin shell: rail, topbar, toolbar, panel, metrics            |
+| `navigation.css` | site nav, menu, theme toggle (dot indicator)                  |
+| `typography.css` | display headings, eyebrows, legacy `.button`                  |
+| `cards.css`      | personal-site semantic cards (token-driven)                   |
+| `layout.css`     | site shell, hero, grids                                       |
+| `responsive.css` | breakpoint overrides                                          |
+## Demo
+`demo/index.html` is a kitchen sink covering every primitive in both themes.
+Serve the package root and open `/demo/`:
+```bash
+python3 -m http.server -d . 8080   # then open http://localhost:8080/demo/
+```
+## Develop
+```bash
+npm install        # stylelint + jsdom (test only)
+npm run check      # lint + 4 integrity checks (exports, tokens, classes, pack)
+npm test           # node:test — pure modules + jsdom behavior tests
+npm run lint:fix   # auto-fix the safe stylistic rules
+npm run tokens:build  # regenerate tokens/index.json from tokens/index.js
+```
+`npm run check` enforces that the data mirrors cannot drift from the CSS:
+exports/import-graph integrity, `tokens.css` ⇄ `tokens/index.{js,json}`, the
+`classes` registry ⇄ the `.ui-*` selectors, and that the published tarball
+ships only the intended files. CI
+(`.github/workflows/ci.yml`) runs it on every branch push and PR. It never
+publishes — a push to `main` ships nothing.
+## Release
+Releases publish to npm and are tag-driven:
+```bash
+# 1. bump "version" in package.json, land on main, let CI go green
+git tag vX.Y.Z && git push origin vX.Y.Z
+```
+The tag triggers `.github/workflows/release.yml`: `validate` (read-only
+checks + tag↔version match) → `publish-npm` (only if validate passes) +
+`release-notes`. **The npm publish is the gate** — a failing check means
+the version never reaches npm, so consumers never resolve it. GitHub also
+serves the raw tag tarball ungated, but that is a legacy/fallback path, not
+the documented install. See [`docs/architecture.md`](docs/architecture.md).
+**Before the first real publish** — one npm-account step remains:
+- Create the `@ponchia` npm scope and add an `NPM_TOKEN` repo secret
+  (an npm automation token with publish rights to the scope).
+Done already: MIT `LICENSE`, `version` `0.2.0`, `publishConfig`, the
+gated publish workflow. After publishing, switch the consumer repos'
+dependency specifier to `@ponchia/ui`.
+## Consumers
+- `personal-site` — imports `@ponchia/ui/css/core.css`
+- `polpo-admin` — imports `@ponchia/ui/css`
+Both still pin the old tarball URL; they switch their dependency to
+`@ponchia/ui` once it is published (separate repos — not changed here).

package/behaviors/index.d.ts ADDED Viewed

@@ -0,0 +1,40 @@
+/** @ponchia/ui — optional, framework-agnostic behaviors. */
+/** Cleanup function returned by every initializer. */
+export type Cleanup = () => void;
+export interface ThemeStorageOpts {
+  /** localStorage key for the persisted theme. Default: "bronto-theme". */
+  storageKey?: string;
+}
+export interface ApplyThemeOpts extends ThemeStorageOpts {
+  /** Element to set `data-theme` on. Default: <html>. */
+  root?: Element;
+}
+export interface DelegateOpts {
+  /** Event-delegation root; also scopes which controls are queried. Default: document. */
+  root?: Document | Element;
+}
+/** `bronto:themechange` CustomEvent detail. */
+export interface ThemeChangeDetail {
+  theme: 'light' | 'dark';
+}
+/** Apply the persisted theme to <html data-theme>. Call before paint. */
+export declare function applyStoredTheme(opts?: ApplyThemeOpts): void;
+/**
+ * Wire `[data-bronto-theme-toggle]` controls. Theme is always applied to
+ * <html>; `root` only scopes delegation/queried controls. Dispatches
+ * `bronto:themechange` on <html>. Returns a cleanup function.
+ */
+export declare function initThemeToggle(opts?: ThemeStorageOpts & DelegateOpts): Cleanup;
+/** Wire `[data-bronto-dismiss]` controls. Returns a cleanup function. */
+export declare function dismissible(opts?: DelegateOpts): Cleanup;
+/** Wire `[data-bronto-disclosure]` triggers. Returns a cleanup function. */
+export declare function initDisclosure(opts?: DelegateOpts): Cleanup;

package/behaviors/index.js ADDED Viewed

@@ -0,0 +1,139 @@
+/**
+ * @ponchia/ui — optional behaviors.
+ *
+ * The framework is CSS-first. This is the sanctioned home for the small
+ * amount of JS that genuinely needs scripting (theme persistence, dismiss,
+ * disclosure), so consumers don't each reimplement it.
+ *
+ * Framework-agnostic, dependency-free, side-effect-free on import, and
+ * SSR-safe (every entry no-ops without a DOM). Each initializer uses event
+ * delegation off a root and returns a cleanup function.
+ *
+ *   import { applyStoredTheme, initThemeToggle } from '@ponchia/ui/behaviors';
+ *   applyStoredTheme();                 // before paint, avoids theme flash
+ *   const stop = initThemeToggle();     // wire [data-bronto-theme-toggle]
+ */
+const THEMES = ['light', 'dark'];
+const noop = () => {};
+const hasDom = () => typeof document !== 'undefined';
+/**
+ * Apply the persisted theme to <html data-theme>. Call as early as
+ * possible (an inline module in <head>) to avoid a flash before the
+ * toggle wires up. No stored value → leaves prefers-color-scheme to act.
+ */
+export function applyStoredTheme({ storageKey = 'bronto-theme', root } = {}) {
+  if (!hasDom()) return;
+  const el = root || document.documentElement;
+  let stored = null;
+  try {
+    stored = localStorage.getItem(storageKey);
+  } catch {
+    /* storage blocked (private mode / sandbox) — fall through to OS default */
+  }
+  if (stored && THEMES.includes(stored)) el.setAttribute('data-theme', stored);
+}
+/**
+ * Wire `[data-bronto-theme-toggle]` controls. Click toggles light/dark,
+ * persists to localStorage, and **always** sets `data-theme` on <html>
+ * (a theme is document-global). State is reflected via `aria-pressed`
+ * and a `bronto:themechange` CustomEvent ({ detail: { theme } }) is
+ * dispatched on <html> so consumers can sync their own UI without
+ * racing the click handler. A control may set
+ * `data-bronto-theme-toggle="dark"` to force a specific theme.
+ *
+ * `root` scopes event delegation and which controls are queried/reflected
+ * (default `document`); it does not change where the theme is applied.
+ */
+export function initThemeToggle({ storageKey = 'bronto-theme', root } = {}) {
+  if (!hasDom()) return noop;
+  const host = root || document;
+  const docEl = document.documentElement;
+  const prefersDark = () =>
+    typeof matchMedia === 'function' && matchMedia('(prefers-color-scheme: dark)').matches;
+  const current = () => {
+    const attr = docEl.getAttribute('data-theme');
+    if (THEMES.includes(attr)) return attr;
+    return prefersDark() ? 'dark' : 'light';
+  };
+  const reflect = () => {
+    const c = current();
+    host.querySelectorAll('[data-bronto-theme-toggle]').forEach((el) => {
+      const forced = el.getAttribute('data-bronto-theme-toggle');
+      // A forced control is "pressed" when its theme is the active one;
+      // a plain toggle reflects whether dark is active.
+      const pressed = THEMES.includes(forced) ? c === forced : c === 'dark';
+      el.setAttribute('aria-pressed', String(pressed));
+    });
+  };
+  const onClick = (e) => {
+    const trigger = e.target.closest('[data-bronto-theme-toggle]');
+    if (!trigger || !host.contains(trigger)) return;
+    const forced = trigger.getAttribute('data-bronto-theme-toggle');
+    const next = THEMES.includes(forced) ? forced : current() === 'dark' ? 'light' : 'dark';
+    docEl.setAttribute('data-theme', next);
+    try {
+      localStorage.setItem(storageKey, next);
+    } catch {
+      /* storage blocked — theme still applies for this session */
+    }
+    reflect();
+    docEl.dispatchEvent(
+      new CustomEvent('bronto:themechange', { detail: { theme: next }, bubbles: true })
+    );
+  };
+  applyStoredTheme({ storageKey });
+  reflect();
+  host.addEventListener('click', onClick);
+  return () => host.removeEventListener('click', onClick);
+}
+/**
+ * Click on `[data-bronto-dismiss]` removes the nearest ancestor matching
+ * `[data-bronto-dismissible]` (or the selector given as the attribute
+ * value). Emits a cancelable `bronto:dismiss` event first.
+ */
+export function dismissible({ root } = {}) {
+  if (!hasDom()) return noop;
+  const host = root || document;
+  const onClick = (e) => {
+    const btn = e.target.closest('[data-bronto-dismiss]');
+    if (!btn || !host.contains(btn)) return;
+    const sel = btn.getAttribute('data-bronto-dismiss');
+    const target = sel ? btn.closest(sel) : btn.closest('[data-bronto-dismissible]');
+    if (!target) return;
+    const ev = new CustomEvent('bronto:dismiss', { bubbles: true, cancelable: true });
+    if (target.dispatchEvent(ev)) target.remove();
+  };
+  host.addEventListener('click', onClick);
+  return () => host.removeEventListener('click', onClick);
+}
+/**
+ * Disclosure: a `[data-bronto-disclosure]` trigger toggles the element
+ * referenced by its `aria-controls` id, keeping `aria-expanded` and the
+ * panel's `hidden` attribute in sync.
+ */
+export function initDisclosure({ root } = {}) {
+  if (!hasDom()) return noop;
+  const host = root || document;
+  const onClick = (e) => {
+    const trigger = e.target.closest('[data-bronto-disclosure]');
+    if (!trigger || !host.contains(trigger)) return;
+    const id = trigger.getAttribute('aria-controls');
+    const panel = id && document.getElementById(id);
+    if (!panel) return;
+    const open = trigger.getAttribute('aria-expanded') === 'true';
+    trigger.setAttribute('aria-expanded', String(!open));
+    panel.hidden = open;
+  };
+  host.addEventListener('click', onClick);
+  return () => host.removeEventListener('click', onClick);
+}

package/classes/index.d.ts ADDED Viewed

@@ -0,0 +1,69 @@
+/** @ponchia/ui — typed class-name contract. */
+export type ClassValue = string | false | null | undefined | ClassValue[];
+/** The flat registry of every class @ponchia/ui defines. */
+export declare const cls: Readonly<Record<string, string>>;
+/** classnames-style joiner: skips falsy, flattens arrays. */
+export declare function cx(...parts: ClassValue[]): string;
+export interface ButtonOpts {
+  variant?: 'ghost' | 'subtle' | 'danger';
+  icon?: boolean;
+}
+export interface CardOpts {
+  accent?: boolean;
+  interactive?: boolean;
+}
+export interface BadgeOpts {
+  tone?: 'accent' | 'success' | 'warning' | 'danger';
+}
+export interface ChipOpts {
+  accent?: boolean;
+}
+export interface LinkOpts {
+  arrow?: boolean;
+}
+export interface DotOpts {
+  tone?: 'accent' | 'success' | 'warning' | 'danger';
+  live?: boolean;
+}
+export interface DotgridOpts {
+  accent?: boolean;
+  dense?: boolean;
+}
+export interface TableOpts {
+  density?: 'dense' | 'comfortable';
+  lined?: boolean;
+}
+export interface EyebrowOpts {
+  muted?: boolean;
+}
+export interface HintOpts {
+  error?: boolean;
+}
+export interface ClusterOpts {
+  between?: boolean;
+}
+export interface StaggerOpts {
+  auto?: boolean;
+}
+export interface Ui {
+  button(opts?: ButtonOpts): string;
+  card(opts?: CardOpts): string;
+  badge(opts?: BadgeOpts): string;
+  chip(opts?: ChipOpts): string;
+  link(opts?: LinkOpts): string;
+  dot(opts?: DotOpts): string;
+  dotgrid(opts?: DotgridOpts): string;
+  table(opts?: TableOpts): string;
+  eyebrow(opts?: EyebrowOpts): string;
+  hint(opts?: HintOpts): string;
+  cluster(opts?: ClusterOpts): string;
+  stagger(opts?: StaggerOpts): string;
+}
+export declare const ui: Ui;
+export default ui;

package/classes/index.js ADDED Viewed

@@ -0,0 +1,159 @@
+/**
+ * @ponchia/ui — typed class-name contract.
+ *
+ * The framework's real API is its class vocabulary. Hand-writing
+ * "ui-button ui-button--ghost" everywhere is untyped and typo-prone, so
+ * this module turns that contract into data + tiny recipe builders:
+ *
+ *   import { ui, cx } from '@ponchia/ui/classes';
+ *   <button class={ui.button({ variant: 'ghost' })}>
+ *   <span class={cx(ui.dot({ tone: 'success' }), 'my-extra')}>
+ *
+ * Framework-agnostic (returns strings). `cls` is the flat registry of
+ * every class the framework defines; recipes only ever emit from it, and
+ * scripts/check-classes.mjs fails CI if any entry is missing from the
+ * stylesheet — so this file cannot drift from the CSS.
+ */
+/** Every class @ponchia/ui defines. The single source the recipes draw from. */
+export const cls = Object.freeze({
+  // primitives
+  button: 'ui-button',
+  buttonGhost: 'ui-button--ghost',
+  buttonSubtle: 'ui-button--subtle',
+  buttonDanger: 'ui-button--danger',
+  buttonIcon: 'ui-button--icon',
+  card: 'ui-card',
+  cardHead: 'ui-card__head',
+  cardAccent: 'ui-card--accent',
+  cardInteractive: 'ui-card--interactive',
+  badge: 'ui-badge',
+  badgeAccent: 'ui-badge--accent',
+  badgeSuccess: 'ui-badge--success',
+  badgeWarning: 'ui-badge--warning',
+  badgeDanger: 'ui-badge--danger',
+  chip: 'ui-chip',
+  chipAccent: 'ui-chip--accent',
+  link: 'ui-link',
+  linkArrow: 'ui-link--arrow',
+  keyValue: 'ui-key-value',
+  // dots
+  dot: 'ui-dot',
+  dotAccent: 'ui-dot--accent',
+  dotSuccess: 'ui-dot--success',
+  dotWarning: 'ui-dot--warning',
+  dotDanger: 'ui-dot--danger',
+  dotLive: 'ui-dot--live',
+  dotgrid: 'ui-dotgrid',
+  dotgridAccent: 'ui-dotgrid--accent',
+  dotgridDense: 'ui-dotgrid--dense',
+  dotfield: 'ui-dotfield',
+  dotrule: 'ui-dotrule',
+  dotbar: 'ui-dotbar',
+  dotloader: 'ui-dotloader',
+  // forms
+  field: 'ui-field',
+  label: 'ui-label',
+  input: 'ui-input',
+  select: 'ui-select',
+  textarea: 'ui-textarea',
+  search: 'ui-search',
+  check: 'ui-check',
+  switch: 'ui-switch',
+  switchTrack: 'ui-switch__track',
+  switchThumb: 'ui-switch__thumb',
+  hint: 'ui-hint',
+  hintError: 'ui-hint--error',
+  // table
+  table: 'ui-table',
+  tableDense: 'ui-table--dense',
+  tableComfortable: 'ui-table--comfortable',
+  tableLined: 'ui-table--lined',
+  tableWrap: 'ui-table-wrap',
+  tableEmpty: 'ui-table__empty',
+  // shell / layout
+  panel: 'ui-panel',
+  panelHead: 'ui-panel__head',
+  surface: 'ui-surface',
+  stack: 'ui-stack',
+  cluster: 'ui-cluster',
+  clusterBetween: 'ui-cluster--between',
+  grid: 'ui-grid',
+  divider: 'ui-divider',
+  status: 'ui-status',
+  // typography / utilities
+  eyebrow: 'ui-eyebrow',
+  eyebrowMuted: 'ui-eyebrow--muted',
+  display: 'ui-display',
+  mono: 'ui-mono',
+  muted: 'ui-muted',
+  visuallyHidden: 'ui-visually-hidden',
+  // motion
+  reveal: 'ui-reveal',
+  stagger: 'ui-stagger',
+  staggerAuto: 'ui-stagger--auto',
+  matrix: 'ui-matrix',
+  skeleton: 'ui-skeleton',
+  spinner: 'ui-spinner',
+  caret: 'ui-caret',
+  animateIn: 'ui-animate-in',
+  animateFade: 'ui-animate-fade',
+  animateDot: 'ui-animate-dot',
+  animateMatrix: 'ui-animate-matrix',
+});
+/** classnames-style joiner: skips falsy, flattens nested arrays of any depth. */
+export function cx(...parts) {
+  const out = [];
+  for (const p of parts.flat(Infinity)) if (p) out.push(p);
+  return out.join(' ');
+}
+const j = (...p) => p.filter(Boolean).join(' ');
+export const ui = {
+  button: ({ variant, icon } = {}) =>
+    j(
+      cls.button,
+      variant === 'ghost' && cls.buttonGhost,
+      variant === 'subtle' && cls.buttonSubtle,
+      variant === 'danger' && cls.buttonDanger,
+      icon && cls.buttonIcon
+    ),
+  card: ({ accent, interactive } = {}) =>
+    j(cls.card, accent && cls.cardAccent, interactive && cls.cardInteractive),
+  badge: ({ tone } = {}) =>
+    j(
+      cls.badge,
+      tone === 'accent' && cls.badgeAccent,
+      tone === 'success' && cls.badgeSuccess,
+      tone === 'warning' && cls.badgeWarning,
+      tone === 'danger' && cls.badgeDanger
+    ),
+  chip: ({ accent } = {}) => j(cls.chip, accent && cls.chipAccent),
+  link: ({ arrow } = {}) => j(cls.link, arrow && cls.linkArrow),
+  dot: ({ tone, live } = {}) =>
+    j(
+      cls.dot,
+      tone === 'accent' && cls.dotAccent,
+      tone === 'success' && cls.dotSuccess,
+      tone === 'warning' && cls.dotWarning,
+      tone === 'danger' && cls.dotDanger,
+      live && cls.dotLive
+    ),
+  dotgrid: ({ accent, dense } = {}) =>
+    j(cls.dotgrid, accent && cls.dotgridAccent, dense && cls.dotgridDense),
+  table: ({ density, lined } = {}) =>
+    j(
+      cls.table,
+      density === 'dense' && cls.tableDense,
+      density === 'comfortable' && cls.tableComfortable,
+      lined && cls.tableLined
+    ),
+  eyebrow: ({ muted } = {}) => j(cls.eyebrow, muted && cls.eyebrowMuted),
+  hint: ({ error } = {}) => j(cls.hint, error && cls.hintError),
+  cluster: ({ between } = {}) => j(cls.cluster, between && cls.clusterBetween),
+  stagger: ({ auto } = {}) => j(cls.stagger, auto && cls.staggerAuto),
+};
+export default ui;