@obinexusltd/obix-component-progress 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OBINexus Computing — Nnamdi Michael Okpala
+
+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,44 @@
+# @obinexusltd/obix-component-progress
+
+**The `ObixProgress` feedback component** — a `role="progressbar"` with a determinate value / min / max or an `indeterminate` busy state, plus optional `aria-valuetext`.
+
+Split out of `@obinexusltd/obix-component-feedback` as an independent package.
+
+```bash
+npm install @obinexusltd/obix-component-progress
+```
+
+> **Zero dependencies.** Data-Oriented: `createX(config)` returns
+> `{ name, state, actions, render }`. Actions are pure
+> `(state, …args) => newState`; `render(state)` is deterministic, HTML-escaped
+> markup (an empty string while hidden). `renderX(config, overrides?)` renders
+> in one call.
+
+## API
+
+```ts
+import { createProgress, renderProgress } from "@obinexusltd/obix-component-progress";
+
+const el = createProgress({ /* see docs/02-usage.md */ });
+el.render(el.state);
+renderProgress({ /* config */ });   // one call
+```
+
+**Actions** — `setValue(state, n)` · `setIndeterminate(state, bool)` · `complete(state)` · `reset(state)` · `setValueText(state, text)`
+
+## Documentation
+
+| # | Guide |
+|---|-------|
+| 01 | [Overview](docs/01-overview.md) |
+| 02 | [Usage & API](docs/02-usage.md) |
+| 03 | [Accessibility](docs/03-accessibility.md) |
+| 04 | [State & rendered HTML](docs/04-state-and-html.md) |
+
+## Related
+
+Part of the OBIX feedback set: `@obinexusltd/obix-component-``toast` · `alert` · `progress` · `loading`.
+
+## License
+
+MIT — OBINexus Computing

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import type { DOPComponent, ProgressConfig, ProgressState } from "./types.js";
+export type { Action, DOPComponent, ProgressConfig, ProgressState } from "./types.js";
+export declare function createProgress(config: ProgressConfig): DOPComponent<ProgressState>;
+export declare function renderProgress(config: ProgressConfig, overrides?: Partial<ProgressState>): string;
+//# 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":"AAcA,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE9E,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AA+BtF,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,YAAY,CAAC,aAAa,CAAC,CAiClF;AAGD,wBAAgB,cAAc,CAC5B,MAAM,EAAE,cAAc,EACtB,SAAS,GAAE,OAAO,CAAC,aAAa,CAAM,GACrC,MAAM,CAGR"}

package/dist/index.js

@@ -0,0 +1,59 @@
+function esc(value) {
+    return String(value ?? "")
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+function clamp(n, lo, hi) {
+    return Math.min(hi, Math.max(lo, n));
+}
+function renderProgressHtml(state) {
+    const span = state.max - state.min || 1;
+    const pct = state.indeterminate ? 0 : (clamp(state.value, state.min, state.max) - state.min) / span * 100;
+    return (`<div class="obix-progress${state.indeterminate ? " obix-progress--indeterminate" : ""}"` +
+        ` role="progressbar"` +
+        `${state.indeterminate ? "" : ` aria-valuenow="${state.value}"`}` +
+        ` aria-valuemin="${state.min}" aria-valuemax="${state.max}"` +
+        ` aria-label="${esc(state.label)}"` +
+        `${state.valueText ? ` aria-valuetext="${esc(state.valueText)}"` : ""}` +
+        `${state.indeterminate ? ' aria-busy="true"' : ""}>` +
+        `<div class="obix-progress__fill"${state.indeterminate ? "" : ` style="width:${pct}%;"`}></div>` +
+        `</div>`);
+}
+export function createProgress(config) {
+    if (!config || typeof config.label !== "string") {
+        throw new TypeError("[obix-component-progress] createProgress: `label` is required");
+    }
+    const state = {
+        value: config.value ?? 0,
+        min: config.min ?? 0,
+        max: config.max ?? 100,
+        indeterminate: config.indeterminate ?? false,
+        label: config.label,
+        valueText: config.valueText ?? null,
+    };
+    const actions = {
+        setValue: (s, value) => ({
+            ...s,
+            value: Number(value),
+            indeterminate: false,
+        }),
+        setIndeterminate: (s, indeterminate) => ({
+            ...s,
+            indeterminate: Boolean(indeterminate),
+        }),
+        complete: (s) => ({ ...s, value: s.max, indeterminate: false }),
+        reset: (s) => ({ ...s, value: s.min }),
+        setValueText: (s, text) => ({
+            ...s,
+            valueText: String(text),
+        }),
+    };
+    return { name: "ObixProgress", state, actions, render: renderProgressHtml };
+}
+export function renderProgress(config, overrides = {}) {
+    const progress = createProgress(config);
+    return progress.render({ ...progress.state, ...overrides });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,24 @@
+export type Action<S> = (state: S, ...args: any[]) => S;
+export interface DOPComponent<S> {
+    name: string;
+    state: S;
+    actions: Record<string, Action<S>>;
+    render: (state: S) => string;
+}
+export interface ProgressConfig {
+    label: string;
+    value?: number;
+    min?: number;
+    max?: number;
+    indeterminate?: boolean;
+    valueText?: string;
+}
+export interface ProgressState {
+    value: number;
+    min: number;
+    max: number;
+    indeterminate: boolean;
+    label: string;
+    valueText: string | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;AAExD,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,CAAC,CAAC;IACT,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IACnC,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,cAAc;IAE7B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,aAAa,EAAE,OAAO,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/docs/01-overview.md

@@ -0,0 +1,26 @@
+# ObixProgress — Overview
+
+`@obinexusltd/obix-component-progress` is one feedback component from the OBIX component set, packaged
+on its own. It is **Data-Oriented** and has **zero runtime dependencies**.
+
+## The shape
+
+```ts
+const progress = createProgress(config);
+progress.name      // "ObixProgress"
+progress.state     // the full component state (see docs/04)
+progress.actions   // pure (state, …args) => state transitions
+progress.render    // (state) => string  — deterministic, HTML-escaped
+```
+
+- **No classes, no lifecycle, no DOM.** Data plus pure functions. You own
+  the timers, event wiring, and where the HTML string goes.
+- **Deterministic render.** `render(state)` returns the same markup for the
+  same state, and an **empty string** while the component is hidden.
+- **Pure actions.** `actions.foo(state, …)` returns a *new* state.
+
+## When to use it
+
+Use `@obinexusltd/obix-component-progress` when you want just this one piece of feedback UI without
+pulling the whole feedback bundle.
+

package/docs/02-usage.md

@@ -0,0 +1,50 @@
+# ObixProgress — Usage & API
+
+```ts
+import { createProgress, renderProgress } from "@obinexusltd/obix-component-progress";
+```
+
+## `createProgress(config)`
+
+Returns a `DOPComponent`: `{ name, state, actions, render }`. Throws
+`TypeError` when a required field is missing or the wrong type.
+
+| Field | Type | Default | Notes |
+|-------|------|---------|-------|
+| `label` | `string` | **required** | `aria-label` for the bar |
+| `value` | `number` | `0` | Current value (clamped to `[min, max]` when rendering the fill) |
+| `min` | `number` | `0` | `aria-valuemin` |
+| `max` | `number` | `100` | `aria-valuemax` |
+| `indeterminate` | `boolean` | `false` | Omits `aria-valuenow`, sets `aria-busy="true"`, adds `--indeterminate` |
+| `valueText` | `string` | `null` | `aria-valuetext`, e.g. `"3 of 10 files"` |
+
+The full `Config` / `State` interfaces are in
+[`src/types.ts`](../src/types.ts), which ships in the package.
+
+## `renderProgress(config, overrides?)`
+
+One-call render — `createProgress(config).render({ ...state, ...overrides })`.
+Pass `{ visible: true }` as an override to render a normally-hidden state for
+snapshots / SSR:
+
+```ts
+renderProgress(config, { visible: true });
+```
+
+## Actions
+
+`setValue(state, n)` (also clears `indeterminate`) · `setIndeterminate(state, bool)` · `complete(state)` (value → `max`) · `reset(state)` (value → `min`) · `setValueText(state, text)`.
+
+Every action is `(state, …args) => newState` and **pure**. Thread state through
+them (directly or via your store) and re-render:
+
+```ts
+const p = createProgress({ label: "Sync", max: 50 });
+let s = p.actions.setValue(p.state, 20);
+console.log(p.render(s));           // aria-valuenow="20"  style="width:40%;"
+s = p.actions.complete(s);
+console.log(p.render(s));           // aria-valuenow="50"  style="width:100%;"
+```
+
+`render(state)` returns `""` whenever the component is not visible — assigning
+it to `innerHTML` cleanly removes the element.

package/docs/03-accessibility.md

@@ -0,0 +1,17 @@
+# ObixProgress — Accessibility
+
+The rendered HTML carries its ARIA inline — there is no separate a11y layer.
+
+- Live-region semantics are built in: `role` / `aria-live` / `aria-atomic`
+  are set from state (e.g. assertive for errors, polite for status).
+- All interpolated text (messages, labels) is HTML-escaped.
+- Dismiss controls are real `<button type="button">` with an `aria-label`.
+
+## Your responsibilities
+
+- Insert the rendered string into a container that already exists in the DOM
+  so the live region is announced when content changes.
+- Drive timers yourself (e.g. call `dismiss` after `state.duration` ms).
+- Manage focus: for a dismissible alert, return focus to the triggering
+  element (`returnFocusId` is carried in state for you to use).
+- Render one instance per container; give toasts a unique `id`.

package/docs/04-state-and-html.md

@@ -0,0 +1,22 @@
+# ObixProgress — State & rendered HTML
+
+## State
+
+The full state object is defined by the `State` interface in
+[`src/types.ts`](../src/types.ts), built from `config` by
+`createProgress`. Plain JSON-serialisable data.
+
+## Rendered HTML
+
+`render(state)` returns a single element as a string, or **`""`** when the
+component is not visible. Attribute order is fixed; only state-driven
+attributes/branches change between renders.
+
+Class names follow the `obix-*` convention
+(`obix-progress`, `obix-progress--<modifier>`).
+No CSS ships with the package.
+
+## Testing
+
+`test/*.test.mjs` (Node’s built-in runner) asserts the rendered string and
+action purity. Run `npm run build && npm test`.

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@obinexusltd/obix-component-progress",
+  "version": "0.1.0",
+  "description": "OBIX ObixProgress — a role=\"progressbar\" with a determinate value / min / max or an indeterminate busy state, plus optional aria-valuetext. Data-Oriented, zero dependencies.",
+  "license": "MIT",
+  "author": "OBINexus Computing — Nnamdi Michael Okpala <okpalan@protonmail.com>",
+  "type": "module",
+  "private": false,
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./src": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "dist",
+    "docs",
+    "test",
+    "README.md",
+    "LICENSE"
+  ],
+  "directories": {
+    "lib": "dist",
+    "doc": "docs",
+    "test": "test"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test \"test/*.test.mjs\"",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "obix",
+    "component",
+    "dop",
+    "accessibility",
+    "progress",
+    "progressbar",
+    "loading",
+    "feedback"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.11.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/obinexusmk2/obix-component-progress.git"
+  }
+}

package/src/index.ts

@@ -0,0 +1,90 @@
+/**
+ * @obinexusltd/obix-component-progress
+ *
+ * The ObixProgress feedback component — a `role="progressbar"` with a
+ * determinate value / min / max, or an `indeterminate` busy state, plus optional
+ * `aria-valuetext`.
+ *
+ * Data-Oriented: `createProgress(config)` returns
+ * `{ name, state, actions, render }`. Actions are pure
+ * `(state, …args) => ProgressState`; `render(state)` is deterministic,
+ * HTML-escaped markup. Zero dependencies.
+ *
+ * Split out of `@obinexusltd/obix-component-feedback`.
+ */
+import type { DOPComponent, ProgressConfig, ProgressState } from "./types.js";
+
+export type { Action, DOPComponent, ProgressConfig, ProgressState } from "./types.js";
+
+function esc(value: unknown): string {
+  return String(value ?? "")
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+function clamp(n: number, lo: number, hi: number): number {
+  return Math.min(hi, Math.max(lo, n));
+}
+
+function renderProgressHtml(state: ProgressState): string {
+  const span = state.max - state.min || 1;
+  const pct = state.indeterminate ? 0 : (clamp(state.value, state.min, state.max) - state.min) / span * 100;
+
+  return (
+    `<div class="obix-progress${state.indeterminate ? " obix-progress--indeterminate" : ""}"` +
+    ` role="progressbar"` +
+    `${state.indeterminate ? "" : ` aria-valuenow="${state.value}"`}` +
+    ` aria-valuemin="${state.min}" aria-valuemax="${state.max}"` +
+    ` aria-label="${esc(state.label)}"` +
+    `${state.valueText ? ` aria-valuetext="${esc(state.valueText)}"` : ""}` +
+    `${state.indeterminate ? ' aria-busy="true"' : ""}>` +
+    `<div class="obix-progress__fill"${state.indeterminate ? "" : ` style="width:${pct}%;"`}></div>` +
+    `</div>`
+  );
+}
+
+export function createProgress(config: ProgressConfig): DOPComponent<ProgressState> {
+  if (!config || typeof config.label !== "string") {
+    throw new TypeError("[obix-component-progress] createProgress: `label` is required");
+  }
+
+  const state: ProgressState = {
+    value: config.value ?? 0,
+    min: config.min ?? 0,
+    max: config.max ?? 100,
+    indeterminate: config.indeterminate ?? false,
+    label: config.label,
+    valueText: config.valueText ?? null,
+  };
+
+  const actions = {
+    setValue: (s: ProgressState, value: unknown): ProgressState => ({
+      ...s,
+      value: Number(value),
+      indeterminate: false,
+    }),
+    setIndeterminate: (s: ProgressState, indeterminate: unknown): ProgressState => ({
+      ...s,
+      indeterminate: Boolean(indeterminate),
+    }),
+    complete: (s: ProgressState): ProgressState => ({ ...s, value: s.max, indeterminate: false }),
+    reset: (s: ProgressState): ProgressState => ({ ...s, value: s.min }),
+    setValueText: (s: ProgressState, text: unknown): ProgressState => ({
+      ...s,
+      valueText: String(text),
+    }),
+  };
+
+  return { name: "ObixProgress", state, actions, render: renderProgressHtml };
+}
+
+/** Render a progress bar's HTML in one call, optionally with state overrides. */
+export function renderProgress(
+  config: ProgressConfig,
+  overrides: Partial<ProgressState> = {},
+): string {
+  const progress = createProgress(config);
+  return progress.render({ ...progress.state, ...overrides });
+}

package/src/types.ts

@@ -0,0 +1,36 @@
+/**
+ * @obinexusltd/obix-component-progress — types.
+ * Zero-dependency Data-Oriented component: { name, state, actions, render }.
+ */
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+export type Action<S> = (state: S, ...args: any[]) => S;
+
+export interface DOPComponent<S> {
+  name: string;
+  state: S;
+  actions: Record<string, Action<S>>;
+  render: (state: S) => string;
+}
+
+export interface ProgressConfig {
+  /** Accessible name for the progress bar. Required. */
+  label: string;
+  value?: number;
+  min?: number;
+  max?: number;
+  /** Busy state with no known value — omits `aria-valuenow`, sets `aria-busy`. */
+  indeterminate?: boolean;
+  /** Human-friendly value string, e.g. `"3 of 10 files"` (`aria-valuetext`). */
+  valueText?: string;
+}
+
+export interface ProgressState {
+  value: number;
+  min: number;
+  max: number;
+  indeterminate: boolean;
+  label: string;
+  valueText: string | null;
+}

package/test/progress.test.mjs

@@ -0,0 +1,27 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createProgress, renderProgress } from "../dist/index.js";
+
+test("factory returns a DOP component shape", () => {
+  const el = createProgress({ label: "Task" });
+  assert.equal(el.name, "ObixProgress");
+  assert.equal(typeof el.render, "function");
+  assert.equal(typeof el.actions, "object");
+  assert.equal(typeof el.render(el.state), "string");
+});
+
+test("required config is validated", () => {
+  assert.throws(() => createProgress(), TypeError);
+  assert.throws(() => createProgress({}), TypeError);
+});
+
+test("render is deterministic", () => {
+  assert.equal(renderProgress({ label: "Task" }), renderProgress({ label: "Task" }));
+});
+
+test("actions are pure — input state is untouched", () => {
+  const el = createProgress({ label: "Task" });
+  const before = JSON.stringify(el.state);
+  for (const k of Object.keys(el.actions)) el.actions[k](el.state, 1);
+  assert.equal(JSON.stringify(el.state), before);
+});