@gjermundgaraba/pixel-paper 0.0.0-stage → 0.1.0

package/LICENSE

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

@@ -1,3 +1,51 @@
-# Temporary Holding Version
+# @gjermundgaraba/pixel-paper
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Printed paper panels for [Foldkit](https://foldkit.dev) applications: Departure Mono, 2px ink borders, solid offset shadows, 12×12 pixel glyphs, paper and plum palettes. For dense working interfaces: queues, boards, consoles, editors.
+
+## Install
+
+```bash
+pnpm add @gjermundgaraba/pixel-paper foldkit @foldkit/ui effect @effect/platform-browser
+```
+
+Foldkit pins `effect` and `@effect/platform-browser` exactly as peers. An app on a later patch keeps one Effect instance by allowing it:
+
+```yaml
+# pnpm-workspace.yaml
+peerDependencyRules:
+  allowedVersions:
+    effect: <the app's version>
+    "@effect/platform-browser": <the app's version>
+```
+
+## Set up
+
+The views ship branded for Foldkit's view identity, so the app's build needs only `foldkit()`. Import the stylesheet once, from the client entry:
+
+```ts
+import "@gjermundgaraba/pixel-paper/pixel-paper.css";
+```
+
+The stylesheet follows the reader's colour scheme. `Scheme.SchemeSwitch` lets them pin one, and `schemeScript` applies it before first paint; write it into the head:
+
+```ts
+import { schemeScript } from "@gjermundgaraba/pixel-paper/scheme";
+
+export default defineConfig({
+  plugins: [
+    foldkit(),
+    {
+      name: "scheme-script",
+      transformIndexHtml: () => [
+        { tag: "script", children: schemeScript, injectTo: "head-prepend" },
+      ],
+    },
+  ],
+});
+```
+
+Provide `Clipboard.layer` as the application's resources where a component copies.
+
+## Licence
+
+MIT. Departure Mono, in `fonts/`, carries its own licence beside it.

package/dist/_virtual/_rolldown/runtime.js

@@ -0,0 +1,13 @@
+import { brandViewResult as __foldkitBrandViewResult } from 'foldkit/brand'
+// \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return __foldkitBrandViewResult((target), "@gjermundgaraba/pixel-paper/_virtual/_rolldown/runtime.js#__exportAll");
+};
+export { __exportAll };

package/dist/announcer/announcer.d.ts

@@ -0,0 +1,35 @@
+import { Effect, Schema } from "effect";
+import * as Command from "foldkit/command";
+import { Html, HtmlBuilder } from "foldkit/html";
+/** The attribute that marks the page's live region, which a test finds it by: Loading's line
+ *  is a `role="status"` too, so counting that role counts more than the one region. */
+export declare const ANNOUNCER_ATTRIBUTE = "data-pixel-paper-announcer";
+/**
+ * The page's one polite live region, empty until something is said. Render exactly one,
+ * placed by the rule every pixel-paper application follows, because an open Dialog makes
+ * everything outside it inert and hidden from screen readers: inside the topmost open Dialog,
+ * otherwise at the end of the body. `LiveRegion.view` renders it with the toast stack, and
+ * `LiveRegion.place` puts them where the rule says.
+ */
+export declare const view: <Message>(h: HtmlBuilder<Message>) => Html;
+/**
+ * Says `text` to screen readers through the page's live region (see `view`). Words said in
+ * the same moment are read together, and the region clears first, so the same words twice
+ * are read twice. Without a region on the page it does nothing. Reports `CompletedAnnounce`.
+ */
+export declare const Announce: Command.CommandDefinitionWithArgs<"Announce", {
+  text: Schema.String;
+}, Effect.Effect<{
+  readonly _tag: "CompletedAnnounce";
+}, never, never>>;
+/**
+ * Inverts the element `selector` finds for one beat (`--motion-flash`): the signal that a
+ * change was committed. A second flash mid-beat restarts it. With `prefers-reduced-motion`
+ * it holds a still 2px ink ring for the beat instead. Return it beside `Announce`, which says
+ * what the flash shows. Reports `CompletedFlash`.
+ */
+export declare const Flash: Command.CommandDefinitionWithArgs<"Flash", {
+  selector: Schema.String;
+}, Effect.Effect<{
+  readonly _tag: "CompletedFlash";
+}, never, never>>;

package/dist/announcer/announcer.js

@@ -0,0 +1,121 @@
+import { brandViewResult as __foldkitBrandViewResult } from 'foldkit/brand'
+import { Array, Duration, Effect, Option, Schema, pipe } from "effect";
+import * as Command from "foldkit/command";
+import { defineMessageUnion } from "foldkit/message";
+import * as Render from "foldkit/render";
+// src/announcer/announcer.ts
+/** What `Announce` and `Flash` report. An application that runs them puts
+*  `CompletedAnnounce: {}` and `CompletedFlash: {}` in its own Message union, which these tags
+*  match, and its update changes nothing for them. */
+const Message = defineMessageUnion({
+	CompletedAnnounce: {},
+	CompletedFlash: {}
+});
+/** The attribute that marks the page's live region, which a test finds it by: Loading's line
+*  is a `role="status"` too, so counting that role counts more than the one region. */
+const ANNOUNCER_ATTRIBUTE = "data-pixel-paper-announcer";
+const ANNOUNCER_SELECTOR = `[${ANNOUNCER_ATTRIBUTE}]`;
+/**
+* The page's one polite live region, empty until something is said. Render exactly one,
+* placed by the rule every pixel-paper application follows, because an open Dialog makes
+* everything outside it inert and hidden from screen readers: inside the topmost open Dialog,
+* otherwise at the end of the body. `LiveRegion.view` renders it with the toast stack, and
+* `LiveRegion.place` puts them where the rule says.
+*/
+const view = (h) => __foldkitBrandViewResult((h.div([
+	h.Class("sr-only"),
+	h.Role("status"),
+	h.AriaLive("polite"),
+	h.Attribute(ANNOUNCER_ATTRIBUTE, "")
+])), "@gjermundgaraba/pixel-paper/announcer/announcer.js#view");
+const GATHER = Duration.millis(30);
+const PENDING_ATTRIBUTE = "data-pixel-paper-announcing";
+const topmostRegion = () => {
+	const regions = Array.fromIterable(document.querySelectorAll(ANNOUNCER_SELECTOR));
+	return __foldkitBrandViewResult((Option.orElse(Array.findLast(regions, (region) => __foldkitBrandViewResult((region.closest("dialog[open]") !== null), "@gjermundgaraba/pixel-paper/announcer/announcer.js#anonymous")), () => __foldkitBrandViewResult((Array.last(regions)), "@gjermundgaraba/pixel-paper/announcer/announcer.js#anonymous~2"))), "@gjermundgaraba/pixel-paper/announcer/announcer.js#topmostRegion");
+};
+const gather = (region, text) => {
+	const maybePending = Option.fromNullishOr(region.getAttribute(PENDING_ATTRIBUTE));
+	region.setAttribute(PENDING_ATTRIBUTE, Option.match(maybePending, {
+		onNone: () => __foldkitBrandViewResult((text), "@gjermundgaraba/pixel-paper/announcer/announcer.js#onNone"),
+		onSome: (said) => __foldkitBrandViewResult((`${said} ${text}`), "@gjermundgaraba/pixel-paper/announcer/announcer.js#onSome")
+	}));
+	return __foldkitBrandViewResult((Option.isNone(maybePending)), "@gjermundgaraba/pixel-paper/announcer/announcer.js#gather");
+};
+const speak = (region) => {
+	region.textContent = region.getAttribute(PENDING_ATTRIBUTE) ?? "";
+	region.removeAttribute(PENDING_ATTRIBUTE);
+};
+const sayIn = (region, text) => __foldkitBrandViewResult((Effect.gen(function* () {
+	if (!(yield* Effect.sync(() => __foldkitBrandViewResult((gather(region, text)), "@gjermundgaraba/pixel-paper/announcer/announcer.js#anonymous~4")))) return;
+	yield* Effect.sync(() => {
+		region.textContent = "";
+	});
+	yield* Effect.sleep(GATHER);
+	yield* Effect.sync(() => {
+		speak(region);
+	});
+})), "@gjermundgaraba/pixel-paper/announcer/announcer.js#sayIn");
+const announce = (text) => __foldkitBrandViewResult((Effect.gen(function* () {
+	yield* Render.afterCommit;
+	const maybeRegion = yield* Effect.sync(topmostRegion);
+	yield* Option.match(maybeRegion, {
+		onNone: () => __foldkitBrandViewResult((Effect.void), "@gjermundgaraba/pixel-paper/announcer/announcer.js#onNone~2"),
+		onSome: (region) => __foldkitBrandViewResult((sayIn(region, text)), "@gjermundgaraba/pixel-paper/announcer/announcer.js#onSome~2")
+	});
+})), "@gjermundgaraba/pixel-paper/announcer/announcer.js#announce");
+const FLASH_ID = "pixel-paper-flash";
+const TIME = /^(?<amount>(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?)(?<unit>m?s)?$/iu;
+const beatOf = (element) => {
+	const time = getComputedStyle(element).getPropertyValue("--motion-flash").trim();
+	const groups = TIME.exec(time)?.groups;
+	return __foldkitBrandViewResult((pipe(Option.fromNullishOr(groups?.["amount"]), Option.map((amount) => __foldkitBrandViewResult((groups?.["unit"]?.toLowerCase() === "ms" ? Number(amount) : Number(amount) * 1e3), "@gjermundgaraba/pixel-paper/announcer/announcer.js#anonymous~8")), Option.filter(Number.isFinite))), "@gjermundgaraba/pixel-paper/announcer/announcer.js#beatOf");
+};
+const prefersReducedMotion = () => __foldkitBrandViewResult((window.matchMedia("(prefers-reduced-motion: reduce)").matches), "@gjermundgaraba/pixel-paper/announcer/announcer.js#prefersReducedMotion");
+const runFlash = (element, beat) => {
+	for (const animation of Array.filter(element.getAnimations(), (running) => __foldkitBrandViewResult((running.id === FLASH_ID), "@gjermundgaraba/pixel-paper/announcer/announcer.js#anonymous~9"))) animation.cancel();
+	if (prefersReducedMotion()) {
+		const ring = "var(--line) solid var(--ink)";
+		element.animate({
+			outline: [ring, ring],
+			outlineOffset: ["-2px", "-2px"]
+		}, {
+			duration: beat,
+			id: FLASH_ID
+		});
+	} else element.animate({ filter: ["invert(1)", "invert(1)"] }, {
+		duration: beat / 2,
+		delay: beat / 4,
+		id: FLASH_ID
+	});
+};
+const flash = (selector) => __foldkitBrandViewResult((Effect.sync(() => {
+	const maybeElement = Option.fromNullishOr(document.querySelector(selector));
+	const maybeFlash = Option.flatMap(maybeElement, (element) => __foldkitBrandViewResult((Option.map(beatOf(element), (beat) => (__foldkitBrandViewResult(({
+		element,
+		beat
+	}), "@gjermundgaraba/pixel-paper/announcer/announcer.js#anonymous~12")))), "@gjermundgaraba/pixel-paper/announcer/announcer.js#anonymous~11"));
+	if (Option.isSome(maybeFlash)) runFlash(maybeFlash.value.element, maybeFlash.value.beat);
+})), "@gjermundgaraba/pixel-paper/announcer/announcer.js#flash");
+/**
+* Says `text` to screen readers through the page's live region (see `view`). Words said in
+* the same moment are read together, and the region clears first, so the same words twice
+* are read twice. Without a region on the page it does nothing. Reports `CompletedAnnounce`.
+*/
+const Announce = Command.define("Announce", {
+	args: { text: Schema.String },
+	messages: [Message.CompletedAnnounce],
+	execute: ({ text }) => __foldkitBrandViewResult((announce(text).pipe(Effect.as(Message.CompletedAnnounce()))), "@gjermundgaraba/pixel-paper/announcer/announcer.js#execute")
+});
+/**
+* Inverts the element `selector` finds for one beat (`--motion-flash`): the signal that a
+* change was committed. A second flash mid-beat restarts it. With `prefers-reduced-motion`
+* it holds a still 2px ink ring for the beat instead. Return it beside `Announce`, which says
+* what the flash shows. Reports `CompletedFlash`.
+*/
+const Flash = Command.define("Flash", {
+	args: { selector: Schema.String },
+	messages: [Message.CompletedFlash],
+	execute: ({ selector }) => __foldkitBrandViewResult((flash(selector).pipe(Effect.as(Message.CompletedFlash()))), "@gjermundgaraba/pixel-paper/announcer/announcer.js#execute~2")
+});
+export { ANNOUNCER_ATTRIBUTE, Announce, Flash, Message, announce, flash, view };

package/dist/announcer/index.d.ts

@@ -0,0 +1,5 @@
+import { ANNOUNCER_ATTRIBUTE, Announce, Flash, view } from "./announcer.js";
+declare namespace index_d_exports {
+  export { ANNOUNCER_ATTRIBUTE, Announce, Flash, view };
+}
+export { ANNOUNCER_ATTRIBUTE, Announce, Flash, index_d_exports, view };

package/dist/announcer/index.js

@@ -0,0 +1,11 @@
+import { brandViewResult as __foldkitBrandViewResult } from 'foldkit/brand'
+import { __exportAll } from "../_virtual/_rolldown/runtime.js";
+import { ANNOUNCER_ATTRIBUTE, Announce, Flash, view } from "./announcer.js";
+// src/announcer/index.ts
+var announcer_exports = /* @__PURE__ */ __exportAll({
+	ANNOUNCER_ATTRIBUTE: () => __foldkitBrandViewResult((ANNOUNCER_ATTRIBUTE), "@gjermundgaraba/pixel-paper/announcer/index.js#ANNOUNCER_ATTRIBUTE"),
+	Announce: () => __foldkitBrandViewResult((Announce), "@gjermundgaraba/pixel-paper/announcer/index.js#Announce"),
+	Flash: () => __foldkitBrandViewResult((Flash), "@gjermundgaraba/pixel-paper/announcer/index.js#Flash"),
+	view: () => __foldkitBrandViewResult((view), "@gjermundgaraba/pixel-paper/announcer/index.js#view")
+});
+export { ANNOUNCER_ATTRIBUTE, Announce, Flash, announcer_exports, view };

package/dist/attributes/attributes.d.ts

@@ -0,0 +1,4 @@
+import { Attribute, ChildAttribute } from "foldkit/html";
+/** Attributes passed through to an element. Never a class: a later class replaces an earlier
+ *  one, so a passthrough class would wipe the system's own. */
+export type Attributes<Message> = ReadonlyArray<Attribute<Message> | ChildAttribute>;

package/dist/banner/banner.d.ts

@@ -0,0 +1,20 @@
+import { Tone } from "../notice/notice.js";
+import { Html, HtmlBuilder } from "foldkit/html";
+/** Configuration for rendering a banner with `view`. */
+export type ViewConfig = Readonly<{
+  /** One sentence: the state, and what happens to the reader's work. */
+  body: ReadonlyArray<Html | string>;
+  /** `Error` (the default): red, a state that stops work (offline). `Warn`: amber, a state
+   *  that is passing (reconnecting). `Ok`: ink, the state just ended (back online), shown
+   *  briefly and then taken away. `Quiet`: tinted, news. */
+  tone?: Tone;
+  /** A control at the right: reconnect, reload. */
+  actions?: ReadonlyArray<Html | string>;
+}>;
+/** A printed slip fixed at the bottom centre, above the status bar: a state the whole
+ *  interface is in (offline, reconnecting, read-only), for as long as it lasts. One at a
+ *  time. It is not a live region, since it arrives already holding its sentence, which would
+ *  go unheard: the application says the state once, when it begins, through the page's live
+ *  region (the `Announcer.Announce` Command). An outcome that comes and goes is a
+ *  toast; a word beside the control that did it is a FlashWord. */
+export declare const view: <Message>(config: ViewConfig, h: HtmlBuilder<Message>) => Html;

package/dist/banner/banner.js

@@ -0,0 +1,18 @@
+import { brandViewResult as __foldkitBrandViewResult } from 'foldkit/brand'
+import { toneGlyphView } from "../notice/notice.js";
+// src/banner/banner.ts
+/** A printed slip fixed at the bottom centre, above the status bar: a state the whole
+*  interface is in (offline, reconnecting, read-only), for as long as it lasts. One at a
+*  time. It is not a live region, since it arrives already holding its sentence, which would
+*  go unheard: the application says the state once, when it begins, through the page's live
+*  region (the `Announcer.Announce` Command). An outcome that comes and goes is a
+*  toast; a word beside the control that did it is a FlashWord. */
+const view = (config, h) => {
+	const { body, tone = "Error", actions = [] } = config;
+	return __foldkitBrandViewResult((h.div([h.Class("banner")], [
+		toneGlyphView({ tone }, h),
+		h.span([], body),
+		...actions
+	])), "@gjermundgaraba/pixel-paper/banner/banner.js#view");
+};
+export { view };

package/dist/banner/index.d.ts

@@ -0,0 +1,5 @@
+import { ViewConfig, view } from "./banner.js";
+declare namespace index_d_exports {
+  export { ViewConfig, view };
+}
+export { type ViewConfig, index_d_exports, view };

package/dist/banner/index.js

@@ -0,0 +1,6 @@
+import { brandViewResult as __foldkitBrandViewResult } from 'foldkit/brand'
+import { __exportAll } from "../_virtual/_rolldown/runtime.js";
+import { view } from "./banner.js";
+// src/banner/index.ts
+var banner_exports = /* @__PURE__ */ __exportAll({ view: () => __foldkitBrandViewResult((view), "@gjermundgaraba/pixel-paper/banner/index.js#view") });
+export { banner_exports, view };

package/dist/bench/bench.d.ts

@@ -0,0 +1,16 @@
+import { Html, HtmlBuilder } from "foldkit/html";
+/** Configuration for rendering a bench with `view`. */
+export type ViewConfig = Readonly<{
+  /** Above the work, at its own height while the work keeps its floor, past which it scrolls:
+   *  a PageHead, notices, and a Rail's open button first. */
+  head: ReadonlyArray<Html | string>;
+  /** The work, taking the rest of the window's height and never less than
+   *  `--bench-work-min`: a Reel, which fills it, and the page's dialogs. */
+  body: ReadonlyArray<Html | string>;
+}>;
+/** A page whose work is the window: its head at its own height, then the work in all the
+ *  height left, from under the top bar to the window's bottom and edge to edge (beside a Rail,
+ *  from the rail's edge). The main landmark (`<main id="main">`). The page does not scroll:
+ *  the work scrolls itself where it must (a reel's columns, sideways), and on a short window
+ *  the head scrolls in what the work's floor leaves it. */
+export declare const view: <Message>(config: ViewConfig, h: HtmlBuilder<Message>) => Html;

package/dist/bench/bench.js

@@ -0,0 +1,12 @@
+import { brandViewResult as __foldkitBrandViewResult } from 'foldkit/brand'
+// src/bench/bench.ts
+/** A page whose work is the window: its head at its own height, then the work in all the
+*  height left, from under the top bar to the window's bottom and edge to edge (beside a Rail,
+*  from the rail's edge). The main landmark (`<main id="main">`). The page does not scroll:
+*  the work scrolls itself where it must (a reel's columns, sideways), and on a short window
+*  the head scrolls in what the work's floor leaves it. */
+const view = (config, h) => {
+	const { head, body } = config;
+	return __foldkitBrandViewResult((h.main([h.Id("main"), h.Class("bench")], [h.div([h.Class("bench-head")], head), h.div([h.Class("bench-work")], body)])), "@gjermundgaraba/pixel-paper/bench/bench.js#view");
+};
+export { view };

package/dist/bench/index.d.ts

@@ -0,0 +1,5 @@
+import { ViewConfig, view } from "./bench.js";
+declare namespace index_d_exports {
+  export { ViewConfig, view };
+}
+export { type ViewConfig, index_d_exports, view };

package/dist/bench/index.js

@@ -0,0 +1,6 @@
+import { brandViewResult as __foldkitBrandViewResult } from 'foldkit/brand'
+import { __exportAll } from "../_virtual/_rolldown/runtime.js";
+import { view } from "./bench.js";
+// src/bench/index.ts
+var bench_exports = /* @__PURE__ */ __exportAll({ view: () => __foldkitBrandViewResult((view), "@gjermundgaraba/pixel-paper/bench/index.js#view") });
+export { bench_exports, view };