@businessdash/sdk 0.9.60 → 0.9.80

package/src/social-core/index.ts

@@ -0,0 +1,103 @@
+/**
+ * `@businessdash/sdk/social` — everything needed to render social links,
+ * without any framework.
+ *
+ * Social links were React-and-Solid-only, and unlike every other gap this one
+ * was never about logic: `resolveSocialProfiles` already gave all eight
+ * bindings the data. What was missing was MARKUP, which cannot be shared
+ * between frameworks the way a controller can.
+ *
+ * So this module shares everything up to the markup — the resolved rows, the
+ * icon URL, and the handful of layout styles the list needs to work at all —
+ * and each binding writes the six elements around it. That keeps the part that
+ * can drift (which platforms exist, how a handle becomes a URL, where the icon
+ * comes from) in one place, and leaves each framework only the part that
+ * genuinely differs.
+ *
+ * @module
+ */
+
+import { resolveSocialProfiles } from "../socials.js";
+
+export type SocialLinkRow = {
+	/** Stable platform key — usable as a list key. */
+	key: string;
+	/** Human label, e.g. "Instagram". Used for `aria-label` and `title`. */
+	label: string;
+	/** Fully-qualified profile URL. */
+	url: string;
+	/**
+	 * Icon URL on the simple-icons CDN, or `null` for a platform with no brand
+	 * icon — render the generic globe glyph in that case.
+	 */
+	iconUrl: string | null;
+};
+
+export type SocialLinksOptions = {
+	/**
+	 * Icon colour for branded glyphs — a hex WITHOUT `#`, or a CSS colour
+	 * keyword. Omit to use each brand's official colour.
+	 */
+	color?: string | undefined;
+};
+
+/**
+ * Resolve a company's `socials` record into render-ready rows.
+ *
+ * The icon URL is built here rather than in each binding because it encodes a
+ * CDN path and a colour convention — two things that should change in one
+ * place, not eight.
+ */
+export function resolveSocialLinks(
+	socials: unknown,
+	options: SocialLinksOptions = {},
+): SocialLinkRow[] {
+	return resolveSocialProfiles(socials).map((row) => ({
+		key: row.key,
+		label: row.label,
+		url: row.url,
+		iconUrl: row.iconSlug
+			? options.color
+				? `https://cdn.simpleicons.org/${row.iconSlug}/${encodeURIComponent(options.color)}`
+				: `https://cdn.simpleicons.org/${row.iconSlug}`
+			: null,
+	}));
+}
+
+/**
+ * The inline styles the list needs to lay out at all.
+ *
+ * Deliberately minimal — flex, wrap, gap, and resetting the list defaults. No
+ * colour, no borders, no sizing beyond the gap: everything visual is left to
+ * the consumer's own CSS via the class props each binding accepts. A component
+ * that ships opinions here is one the consumer has to fight.
+ */
+export const SOCIAL_LIST_STYLE: Readonly<Record<string, string>> = {
+	display: "flex",
+	"flex-wrap": "wrap",
+	"align-items": "center",
+	gap: "0.75rem",
+	"list-style": "none",
+	margin: "0",
+	padding: "0",
+};
+
+/** The same, as a `style="…"` string for bindings that take one. */
+export const SOCIAL_LIST_STYLE_STRING: string = Object.entries(
+	SOCIAL_LIST_STYLE,
+)
+	.map(([k, v]) => `${k}:${v}`)
+	.join(";");
+
+/**
+ * The fallback glyph for a platform with no brand icon, as an SVG path set.
+ *
+ * Shared so a consumer sees the same generic mark whichever framework they
+ * chose, rather than eight subtly different circles.
+ */
+export const SOCIAL_FALLBACK_GLYPH = {
+	viewBox: "0 0 24 24",
+	strokeWidth: 1.8,
+	circle: { cx: 12, cy: 12, r: 9 },
+	path: "M3 12h18M12 3a14 14 0 0 1 0 18M12 3a14 14 0 0 0 0 18",
+} as const;

package/src/social.ts

@@ -0,0 +1,7 @@
+/**
+ * `@businessdash/sdk/social` — framework-free social-link resolution.
+ *
+ * @module
+ */
+
+export * from "./social-core/index.js";

package/src/solid-compat.tsx

@@ -0,0 +1,347 @@
+/**
+ * The slice of Solid this SDK uses, written so one binding works on **both**
+ * Solid 1 and Solid 2.
+ *
+ * ## Why this exists
+ *
+ * Solid 2 reorganised its public API. Measured against the published packages
+ * rather than assumed:
+ *
+ * | symbol | Solid 1 | Solid 2 |
+ * |---|---|---|
+ * | `createSignal` `createMemo` `createEffect` | `solid-js` | `solid-js` |
+ * | `createContext` `useContext` `onCleanup` | `solid-js` | `solid-js` |
+ * | `mapArray` `children` `untrack` | `solid-js` | `solid-js` |
+ * | `For` `Show` `Switch` `Match` | `solid-js` | **`@solidjs/web`** |
+ * | `onMount` `createUniqueId` `from` | `solid-js` | **gone** |
+ * | `Accessor` `JSX` (types) | `solid-js` | **gone** |
+ *
+ * A static import cannot branch on which version is installed, and the build
+ * here is plain `tsc` with no aliasing step — so the two-entry-point trick is
+ * not available either. What IS available is the intersection: every primitive
+ * in the first three rows exists, unchanged, in both versions.
+ *
+ * So this module rebuilds the missing pieces on top of that intersection. The
+ * binding then imports control flow from here instead of from `solid-js`, and
+ * the same compiled output runs on either version.
+ *
+ * ## Why not just use plain JSX instead
+ *
+ * `{items().map(...)}` would have been less code. It also throws away `For`'s
+ * keyed reconciliation — Solid re-creates every row when the array identity
+ * changes, instead of moving the DOM nodes it already has. That is a real
+ * performance characteristic of a form renderer with 200 fields, not sugar, so
+ * `For` here is built over `mapArray`, which is the same primitive Solid's own
+ * `For` uses and which exists in both versions.
+ *
+ * @module
+ */
+
+import {
+	children,
+	createMemo,
+	createSignal,
+	mapArray,
+	onCleanup,
+	untrack,
+} from "solid-js";
+
+/**
+ * A reactive getter. `Accessor` in Solid 1; nothing in Solid 2, where it is
+ * spelled as the plain function type it always was.
+ */
+export type Accessor<T> = () => T;
+
+/**
+ * Anything Solid will render.
+ *
+ * Deliberately not `JSX.Element`: that type lives in `solid-js` on 1 and in
+ * `@solidjs/web` on 2, so naming it would reintroduce the split this module
+ * exists to remove. Written structurally instead, as the union both versions
+ * accept — measured from their `jsx.d.ts`:
+ *
+ *   Solid 1: `Node | ArrayElement | (string & {}) | number | boolean | null | undefined`
+ *   Solid 2: `SolidElement | Node | ArrayElement`
+ *
+ * The function arm matters: every component here returns a `createMemo`, and a
+ * memo is a function. Solid renders it lazily, which is what keeps unselected
+ * `Switch` branches from evaluating.
+ */
+export type SolidNode = unknown;
+
+/**
+ * Hand a `SolidNode` back to JSX.
+ *
+ * One cast, in one place, and it is unavoidable rather than lazy: the two
+ * versions disagree about what `JSX.Element` IS — Solid 2 adds a
+ * `RenderedElement` arm Solid 1 has never heard of — so no single named type
+ * is assignable in both directions. Accepting children permissively and
+ * narrowing once at the boundary is what Solid's own components do, and it
+ * keeps the cast auditable instead of scattering `as` through the render tree.
+ */
+export function renderNode(node: SolidNode): Node {
+	return node as Node;
+}
+
+/**
+ * What these components RETURN.
+ *
+ * `Node` rather than `SolidNode`, because TypeScript checks a component's
+ * return type against the installed version's `JSX.Element`, and `Node` is the
+ * only arm those two unions share:
+ *
+ *   Solid 1: `Node | ArrayElement | (string & {}) | number | boolean | null | undefined`
+ *   Solid 2: `SolidElement | Node | ArrayElement`
+ *
+ * The values really returned are memos — functions — which Solid renders
+ * lazily. Solid's own `For` does the same thing and casts for the same reason;
+ * the cast is at the JSX boundary only, and every value flowing THROUGH these
+ * components stays typed as `SolidNode`.
+ */
+
+/**
+ * An inline style object.
+ *
+ * `JSX.CSSProperties` lives in `solid-js` on Solid 1 and `@solidjs/web` on
+ * Solid 2, so naming it would reintroduce the split. Solid accepts a plain
+ * record of CSS property names to values, which is all these are.
+ */
+export type SolidStyle = Record<string, string | number | undefined>;
+
+/**
+ * Keyed list rendering.
+ *
+ * `mapArray` is the primitive under Solid's own `For` and is exported by both
+ * versions, so this keeps the reconciliation behaviour rather than degrading
+ * to a re-render on every array identity change.
+ */
+export function For<T>(props: {
+	each: readonly T[] | undefined | null;
+	children: (item: T, index: Accessor<number>) => SolidNode;
+}): Node {
+	// `props.each` is read inside the memo so the list stays reactive; reading
+	// it here would snapshot it once and never update.
+	const mapped = createMemo(
+		mapArray(
+			() => props.each ?? [],
+			(item, index) => props.children(item, index),
+		),
+	);
+	return mapped as unknown as Node;
+}
+
+/**
+ * Conditional rendering.
+ *
+ * The children are only evaluated when the condition holds, which is the whole
+ * point — an eagerly-evaluated branch would run effects and fetches for UI
+ * nobody is looking at.
+ */
+// Overloads, not a union. `SolidNode` is `unknown`, and `unknown | Fn`
+// collapses back to `unknown` — which makes TypeScript unable to see the
+// function arm at all, so `{(item) => ...}` children get an implicit-any
+// parameter. Overload resolution picks the callable form properly.
+export function Show<T>(props: {
+	when: T | undefined | null | false;
+	fallback?: SolidNode;
+	children: (item: Accessor<NonNullable<T>>) => SolidNode;
+}): Node;
+export function Show<T>(props: {
+	when: T | undefined | null | false;
+	fallback?: SolidNode;
+	children: SolidNode;
+}): Node;
+export function Show<T>(props: {
+	when: T | undefined | null | false;
+	fallback?: SolidNode;
+	children: SolidNode | ((item: Accessor<NonNullable<T>>) => SolidNode);
+}): Node {
+	const condition = createMemo(() => props.when);
+	return createMemo(() => {
+		const value = condition();
+		if (!value) return props.fallback;
+		const body = props.children;
+		if (typeof body !== "function") return body;
+		// An accessor, matching Solid's own signature: the child is written as
+		// `{(item) => <b>{item()}</b>}` and calling it keeps the read tracked
+		// inside the child rather than at the boundary.
+		const accessor: Accessor<NonNullable<T>> = () =>
+			condition() as NonNullable<T>;
+		return untrack(() =>
+			(body as (item: Accessor<NonNullable<T>>) => SolidNode)(accessor),
+		);
+	}) as unknown as Node;
+}
+
+/** The marker a `Match` leaves behind for its enclosing `Switch`. */
+type MatchMarker = {
+	readonly __biabMatch: true;
+	readonly when: unknown;
+	readonly children: SolidNode;
+};
+
+function isMatchMarker(value: unknown): value is MatchMarker {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		(value as { __biabMatch?: unknown }).__biabMatch === true
+	);
+}
+
+/**
+ * One branch of a `Switch`.
+ *
+ * Returns a descriptor rather than DOM. `children` is a GETTER so the branch
+ * body is not evaluated unless `Switch` picks it — Solid's props are lazy, and
+ * forwarding that laziness is what keeps unselected branches inert.
+ */
+export function Match(props: { when: unknown; children: SolidNode }): Node {
+	const marker: MatchMarker = {
+		__biabMatch: true,
+		get when() {
+			return props.when;
+		},
+		get children() {
+			return props.children;
+		},
+	};
+	return marker as unknown as Node;
+}
+
+/**
+ * First matching branch wins, else `fallback`.
+ *
+ * `children()` resolves the JSX children — which invokes each `Match` and
+ * yields its marker — and the memo re-picks whenever any `when` changes.
+ */
+export function Switch(props: {
+	fallback?: SolidNode;
+	children: SolidNode;
+}): Node {
+	const resolved = children(() => props.children as never);
+	return createMemo(() => {
+		const list = resolved.toArray() as unknown[];
+		for (const entry of list) {
+			if (!isMatchMarker(entry)) continue;
+			if (entry.when) return entry.children;
+		}
+		return props.fallback;
+	}) as unknown as Node;
+}
+
+/**
+ * Run once, after the first render.
+ *
+ * Solid 2 dropped `onMount`; it was always `createEffect` with the body
+ * untracked and a guard. Written out rather than imported so the binding does
+ * not care which version it is on.
+ */
+export function onMount(fn: () => void): void {
+	const [mounted, setMounted] = createSignal(false);
+	createMemo(() => {
+		if (mounted()) return;
+		setMounted(true);
+		untrack(fn);
+	});
+}
+
+/**
+ * The provider component for a context, on either Solid version.
+ *
+ * Solid 1 hangs a `.Provider` off the context object. Solid 2 makes the
+ * context object **its own provider** — you write `<Ctx value={x}>` where you
+ * used to write `<Ctx.Provider value={x}>`.
+ *
+ * Unlike the import differences, this one CAN be resolved at runtime: the
+ * shape is inspectable. `.Provider` when it exists, the context itself
+ * otherwise.
+ */
+export function providerFor<T>(
+	context: unknown,
+): (props: { value: T; children: SolidNode }) => Node {
+	const withProvider = context as {
+		Provider?: (props: { value: T; children: SolidNode }) => Node;
+	};
+	return (
+		withProvider.Provider ??
+		(context as (props: { value: T; children: SolidNode }) => Node)
+	);
+}
+
+/**
+ * Build a `class` string from a base plus conditional modifiers.
+ *
+ * Replaces Solid 1's `classList={{ "mod": cond }}`, which Solid 2 removed —
+ * verified against both versions' `jsx.d.ts`, where `classList` is declared in
+ * 1 and absent in 2.
+ *
+ * A plain `class` string behaves identically on both, so this is the portable
+ * spelling rather than a workaround.
+ */
+export function cx(
+	base: string | undefined,
+	modifiers?: Record<string, boolean | undefined>,
+): string {
+	const parts = base ? [base] : [];
+	if (modifiers) {
+		for (const [name, on] of Object.entries(modifiers)) {
+			if (on) parts.push(name);
+		}
+	}
+	return parts.join(" ");
+}
+
+let uniqueIdCounter = 0;
+
+/**
+ * A stable id for `for`/`aria-*` pairs.
+ *
+ * Solid 2 dropped `createUniqueId`. A module-level counter is enough here
+ * because these ids are only ever used to link a label to its own input within
+ * one document — they are not persisted, sent anywhere, or compared across
+ * renders.
+ *
+ * The `biab-` prefix keeps them from colliding with ids the consumer's own
+ * page already uses.
+ */
+export function createUniqueId(): string {
+	uniqueIdCounter += 1;
+	return `biab-${uniqueIdCounter}`;
+}
+
+/**
+ * Bridge an external store into a signal.
+ *
+ * Replaces Solid 1's `from`, which Solid 2 dropped. The shape is exactly what
+ * every shared core exposes — `snapshot()` / `subscribe()` / `destroy()` — so
+ * this is the one seam where the framework-agnostic controllers meet Solid.
+ *
+ * `subscribe` does NOT replay, so the initial value is read separately. A
+ * bridge that waited for the first notification would render empty until
+ * something happened to change, which on a quiet screen is forever.
+ */
+export function fromStore<T>(store: {
+	snapshot: () => T;
+	subscribe: (listener: () => void) => () => void;
+}): Accessor<T> {
+	// Boxed, and not for tidiness: Solid 2 types the value overload of
+	// `createSignal` as `Exclude<T, Function>`, because a bare function
+	// argument is read as a compute function instead of a value. A snapshot
+	// type that could be callable is therefore rejected outright. A wrapper
+	// object is never a Function, so the same call compiles on both versions
+	// and cannot be mistaken for a computation.
+	const [box, setBox] = createSignal<{ value: T }>(
+		{ value: store.snapshot() },
+		{
+			// Snapshots are replaced wholesale, and two structurally-equal
+			// snapshots are still a real update to the controller. Comparing
+			// would drop legitimate notifications.
+			equals: false,
+		},
+	);
+	const unsubscribe = store.subscribe(() =>
+		setBox({ value: store.snapshot() }),
+	);
+	onCleanup(unsubscribe);
+	return () => box().value;
+}