@obinexusltd/obix-component-loading 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-loading
+
+**The `ObixLoading` feedback component** — a `role="status"` spinner with an accessible label and an optional full-area `overlay`; starts hidden.
+
+Split out of `@obinexusltd/obix-component-feedback` as an independent package.
+
+```bash
+npm install @obinexusltd/obix-component-loading
+```
+
+> **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 { createLoading, renderLoading } from "@obinexusltd/obix-component-loading";
+
+const el = createLoading({ /* see docs/02-usage.md */ });
+el.render(el.state);
+renderLoading({ /* config */ });   // one call
+```
+
+**Actions** — `show(state)` · `hide(state)` · `setLabel(state, label)`
+
+## 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, LoadingConfig, LoadingState } from "./types.js";
+export type { Action, DOPComponent, LoadingConfig, LoadingState } from "./types.js";
+export declare function createLoading(config?: LoadingConfig): DOPComponent<LoadingState>;
+export declare function renderLoading(config?: LoadingConfig, overrides?: Partial<LoadingState>): 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,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE5E,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAsBpF,wBAAgB,aAAa,CAAC,MAAM,GAAE,aAAkB,GAAG,YAAY,CAAC,YAAY,CAAC,CAkBpF;AAGD,wBAAgB,aAAa,CAC3B,MAAM,GAAE,aAAkB,EAC1B,SAAS,GAAE,OAAO,CAAC,YAAY,CAAM,GACpC,MAAM,CAGR"}

package/dist/index.js

@@ -0,0 +1,38 @@
+function esc(value) {
+    return String(value ?? "")
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+function renderLoadingHtml(state) {
+    if (!state.visible)
+        return "";
+    return (`<div class="obix-loading${state.overlay ? " obix-loading--overlay" : ""}"` +
+        ` role="status" aria-live="polite" aria-busy="${state.visible}"` +
+        ` aria-label="${esc(state.label)}">` +
+        `<div class="obix-loading__spinner" aria-hidden="true"></div>` +
+        `<span class="obix-loading__label">${esc(state.label)}</span>` +
+        `</div>`);
+}
+export function createLoading(config = {}) {
+    if (!config || typeof config !== "object") {
+        throw new TypeError("[obix-component-loading] createLoading: config must be an object");
+    }
+    const state = {
+        visible: false,
+        label: config.label ?? "Loading…",
+        overlay: config.overlay ?? false,
+    };
+    const actions = {
+        show: (s) => ({ ...s, visible: true }),
+        hide: (s) => ({ ...s, visible: false }),
+        setLabel: (s, label) => ({ ...s, label: String(label) }),
+    };
+    return { name: "ObixLoading", state, actions, render: renderLoadingHtml };
+}
+export function renderLoading(config = {}, overrides = {}) {
+    const loading = createLoading(config);
+    return loading.render({ ...loading.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":"AAkBA,SAAS,GAAG,CAAC,KAAc;IACzB,OAAO,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC;SACvB,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC;SACtB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;SACrB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;SACrB,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;AAC7B,CAAC;AAED,SAAS,iBAAiB,CAAC,KAAmB;IAC5C,IAAI,CAAC,KAAK,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IAC9B,OAAO,CACL,2BAA2B,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,wBAAwB,CAAC,CAAC,CAAC,EAAE,GAAG;QAC3E,gDAAgD,KAAK,CAAC,OAAO,GAAG;QAChE,gBAAgB,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI;QACpC,8DAA8D;QAC9D,qCAAqC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS;QAC9D,QAAQ,CACT,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,SAAwB,EAAE;IACtD,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC1C,MAAM,IAAI,SAAS,CAAC,kEAAkE,CAAC,CAAC;IAC1F,CAAC;IAED,MAAM,KAAK,GAAiB;QAC1B,OAAO,EAAE,KAAK;QACd,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,UAAU;QACjC,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,KAAK;KACjC,CAAC;IAEF,MAAM,OAAO,GAAG;QACd,IAAI,EAAE,CAAC,CAAe,EAAgB,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QAClE,IAAI,EAAE,CAAC,CAAe,EAAgB,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QACnE,QAAQ,EAAE,CAAC,CAAe,EAAE,KAAc,EAAgB,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;KAC9F,CAAC;IAEF,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;AAC5E,CAAC;AAGD,MAAM,UAAU,aAAa,CAC3B,SAAwB,EAAE,EAC1B,YAAmC,EAAE;IAErC,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IACtC,OAAO,OAAO,CAAC,MAAM,CAAC,EAAE,GAAG,OAAO,CAAC,KAAK,EAAE,GAAG,SAAS,EAAE,CAAC,CAAC;AAC5D,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,17 @@
+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 LoadingConfig {
+    label?: string;
+    overlay?: boolean;
+}
+export interface LoadingState {
+    visible: boolean;
+    label: string;
+    overlay: boolean;
+}
+//# 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,aAAa;IAE5B,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAE3B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;CAClB"}

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 @@
+# ObixLoading — Overview
+
+`@obinexusltd/obix-component-loading` 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 loading = createLoading(config);
+loading.name      // "ObixLoading"
+loading.state     // the full component state (see docs/04)
+loading.actions   // pure (state, …args) => state transitions
+loading.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-loading` when you want just this one piece of feedback UI without
+pulling the whole feedback bundle.
+

package/docs/02-usage.md

@@ -0,0 +1,46 @@
+# ObixLoading — Usage & API
+
+```ts
+import { createLoading, renderLoading } from "@obinexusltd/obix-component-loading";
+```
+
+## `createLoading(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` | `"Loading…"` | `aria-label` + visible label text |
+| `overlay` | `boolean` | `false` | Add `obix-loading--overlay` to cover the container |
+
+The full `Config` / `State` interfaces are in
+[`src/types.ts`](../src/types.ts), which ships in the package.
+
+## `renderLoading(config, overrides?)`
+
+One-call render — `createLoading(config).render({ ...state, ...overrides })`.
+Pass `{ visible: true }` as an override to render a normally-hidden state for
+snapshots / SSR:
+
+```ts
+renderLoading(config, { visible: true });
+```
+
+## Actions
+
+`show(state)` · `hide(state)` · `setLabel(state, label)` — state starts `visible: false`.
+
+Every action is `(state, …args) => newState` and **pure**. Thread state through
+them (directly or via your store) and re-render:
+
+```ts
+const l = createLoading({ label: "Loading dashboard…", overlay: true });
+mount.innerHTML = l.render(l.state);              // "" — hidden by default
+mount.innerHTML = l.render(l.actions.show(l.state)); // <div role="status" aria-busy="true">
+// … when the fetch resolves:
+mount.innerHTML = l.render(l.actions.hide(l.state)); // ""
+```
+
+`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 @@
+# ObixLoading — 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 @@
+# ObixLoading — 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
+`createLoading`. 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-loading`, `obix-loading--<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-loading",
+  "version": "0.1.0",
+  "description": "OBIX ObixLoading — a role=\"status\" spinner with an accessible label and an optional full-area overlay; starts hidden. 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",
+    "loading",
+    "spinner",
+    "busy",
+    "feedback"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.11.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/obinexusmk2/obix-component-loading.git"
+  }
+}

package/src/index.ts

@@ -0,0 +1,66 @@
+/**
+ * @obinexusltd/obix-component-loading
+ *
+ * The ObixLoading feedback component — a `role="status"` spinner with an
+ * accessible label and an optional full-area `overlay`. Starts hidden; call
+ * `show` to display it.
+ *
+ * Data-Oriented: `createLoading(config)` returns
+ * `{ name, state, actions, render }`. Actions are pure
+ * `(state, …args) => LoadingState`; `render(state)` is deterministic,
+ * HTML-escaped markup, or `""` while hidden. Zero dependencies.
+ *
+ * Split out of `@obinexusltd/obix-component-feedback`.
+ */
+import type { DOPComponent, LoadingConfig, LoadingState } from "./types.js";
+
+export type { Action, DOPComponent, LoadingConfig, LoadingState } from "./types.js";
+
+function esc(value: unknown): string {
+  return String(value ?? "")
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+function renderLoadingHtml(state: LoadingState): string {
+  if (!state.visible) return "";
+  return (
+    `<div class="obix-loading${state.overlay ? " obix-loading--overlay" : ""}"` +
+    ` role="status" aria-live="polite" aria-busy="${state.visible}"` +
+    ` aria-label="${esc(state.label)}">` +
+    `<div class="obix-loading__spinner" aria-hidden="true"></div>` +
+    `<span class="obix-loading__label">${esc(state.label)}</span>` +
+    `</div>`
+  );
+}
+
+export function createLoading(config: LoadingConfig = {}): DOPComponent<LoadingState> {
+  if (!config || typeof config !== "object") {
+    throw new TypeError("[obix-component-loading] createLoading: config must be an object");
+  }
+
+  const state: LoadingState = {
+    visible: false,
+    label: config.label ?? "Loading…",
+    overlay: config.overlay ?? false,
+  };
+
+  const actions = {
+    show: (s: LoadingState): LoadingState => ({ ...s, visible: true }),
+    hide: (s: LoadingState): LoadingState => ({ ...s, visible: false }),
+    setLabel: (s: LoadingState, label: unknown): LoadingState => ({ ...s, label: String(label) }),
+  };
+
+  return { name: "ObixLoading", state, actions, render: renderLoadingHtml };
+}
+
+/** Render a loading indicator's HTML in one call, optionally with state overrides. */
+export function renderLoading(
+  config: LoadingConfig = {},
+  overrides: Partial<LoadingState> = {},
+): string {
+  const loading = createLoading(config);
+  return loading.render({ ...loading.state, ...overrides });
+}

package/src/types.ts

@@ -0,0 +1,29 @@
+/**
+ * @obinexusltd/obix-component-loading — 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 LoadingConfig {
+  /** Accessible label. Default `"Loading…"`. */
+  label?: string;
+  /** Cover the containing area with an overlay. Default `false`. */
+  overlay?: boolean;
+}
+
+export interface LoadingState {
+  /** Starts `false` — call `show` to display. */
+  visible: boolean;
+  label: string;
+  overlay: boolean;
+}

package/test/loading.test.mjs

@@ -0,0 +1,40 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createLoading, renderLoading } from "../dist/index.js";
+
+test("factory returns a DOP component shape", () => {
+  const el = createLoading({ label: "Loading" });
+  assert.equal(el.name, "ObixLoading");
+  assert.equal(typeof el.render, "function");
+  assert.equal(typeof el.actions, "object");
+  assert.equal(typeof el.render(el.state), "string");
+});
+
+test("config is optional; a non-object arg throws", () => {
+  assert.doesNotThrow(() => createLoading());
+  assert.doesNotThrow(() => createLoading({}));
+  assert.throws(() => createLoading(42), TypeError);
+});
+
+test("starts hidden -> render is an empty string until shown", () => {
+  const el = createLoading({ label: "Please wait" });
+  assert.equal(el.render(el.state), "");
+  const shown = el.actions.show(el.state);
+  assert.match(el.render(shown), /role="status"/);
+  assert.match(el.render(shown), /aria-busy="true"/);
+});
+
+test("render is deterministic and escapes the label", () => {
+  const a = renderLoading({ label: "A & B <x>" }, { visible: true });
+  const b = renderLoading({ label: "A & B <x>" }, { visible: true });
+  assert.equal(a, b);
+  assert.match(a, /A &amp; B &lt;x&gt;/);
+  assert.doesNotMatch(a, /<x>/);
+});
+
+test("actions are pure - input state is untouched", () => {
+  const el = createLoading({ label: "x" });
+  const before = JSON.stringify(el.state);
+  for (const k of Object.keys(el.actions)) el.actions[k](el.state, "y");
+  assert.equal(JSON.stringify(el.state), before);
+});