@dloizides/ui-media 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+- Initial release: ImagePickerButton, useImageUpload, PhotoFramingEditor, PHOTO_FRAMING_BOUNDS + clampFraming (parity with kefi-landings photoTransform), framework-free ./framing subpath.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 dloizides
+
+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,11 @@
+# @dloizides/ui-media
+
+Themable React Native (RN-web) media controls for the dloizides.com UI kit.
+
+- `ImagePickerButton` - one upload slot: idle / uploading / error / done. You pass the `upload(file)` function; the package has no network code. Default picker is the browser file dialog; pass `pickFile` on native.
+- `PhotoFramingEditor` - live preview of your own card (`renderPreview({ framing, transform })`), zoom stepper and position d-pad (44px ui-buttons IconButtons). Value `{ x, y, scale }`.
+- `PHOTO_FRAMING_BOUNDS`, `clampFraming`, `stepFraming`, `framingToTransform` - also importable from the framework-free `@dloizides/ui-media/framing` subpath (no react / react-native import).
+
+All strings arrive through `labels` props (pass your FM() keys). Theme comes from `FeedbackUiProvider` (@dloizides/ui-feedback).
+
+Peers: react, react-native, @dloizides/ui-buttons, @dloizides/ui-feedback, @dloizides/ui-layout.

package/dist/framing.d.mts

@@ -0,0 +1,95 @@
+/**
+ * Photo framing: the `{x, y, scale}` an organiser sets on a performer card.
+ *
+ * The bounds MIRROR `kefi-landings/src/lib/config-to-site.ts` (`photoTransform`,
+ * MAX_PHOTO_OFFSET_PCT / MIN_PHOTO_SCALE / MAX_PHOTO_SCALE), which is what the
+ * public landing page renders. The editor must never offer a value the landing
+ * page would silently clamp away, so the numbers here and there must stay equal.
+ * KEFI-PEOPLE-1 T12 "import the bounds instead of hard-coding them" removes the copy.
+ *
+ * This file imports nothing: it backs the framework-free `@dloizides/ui-media/framing`
+ * subpath.
+ */
+/** A framing value after clamping: every field finite and inside the bounds. */
+interface PhotoFraming {
+    /** Horizontal nudge, % of the card. Negative = left. */
+    readonly x: number;
+    /** Vertical nudge, % of the card. Negative = up. */
+    readonly y: number;
+    /** Zoom factor. 1 = the photo's natural cover fit. */
+    readonly scale: number;
+}
+/** What config / an API may hold: any field missing, null or non-finite. */
+interface PhotoFramingInput {
+    x?: number | null;
+    y?: number | null;
+    scale?: number | null;
+}
+declare const PHOTO_FRAMING_BOUNDS: Readonly<{
+    /** Widest nudge, as a percentage of the card, in either direction. */
+    maxOffsetPct: 60;
+    /** Below 1 the photo shrinks inside an already-roomy frame. */
+    minScale: 0.5;
+    /** Far above 2 the subject's head leaves the card entirely. */
+    maxScale: 3;
+}>;
+declare const DEFAULT_PHOTO_FRAMING: PhotoFraming;
+/**
+ * Normalises any stored framing: non-finite fields fall back to the default,
+ * the rest are clamped to {@link PHOTO_FRAMING_BOUNDS}. Same rules as the
+ * landing page's `photoTransform`, so what the editor previews is what ships.
+ */
+declare function clampFraming(input?: PhotoFramingInput | null): PhotoFraming;
+/** True when the framing is the identity (the landing page emits no transform). */
+declare const isDefaultFraming: (framing: PhotoFraming) => boolean;
+/**
+ * An RN `transform` array. Percent translates are relative to the element
+ * itself on RN-web, matching the landing page's CSS `translate(x%, y%) scale(s)`.
+ * Typed locally so this module stays free of a react-native import.
+ */
+type PhotoFramingTransform = [
+    {
+        translateX: `${number}%`;
+    },
+    {
+        translateY: `${number}%`;
+    },
+    {
+        scale: number;
+    }
+];
+declare const framingToTransform: (framing: PhotoFraming) => PhotoFramingTransform;
+
+/**
+ * The seven controls of the framing editor. An `as const` object rather than a
+ * TS `const enum`: a const enum shipped in a .d.ts cannot be read by consumers
+ * compiled with `isolatedModules` (every Expo / Babel portal).
+ */
+declare const FramingAction: {
+    readonly ZoomIn: "zoomIn";
+    readonly ZoomOut: "zoomOut";
+    readonly MoveUp: "moveUp";
+    readonly MoveDown: "moveDown";
+    readonly MoveLeft: "moveLeft";
+    readonly MoveRight: "moveRight";
+    readonly Reset: "reset";
+};
+type FramingAction = (typeof FramingAction)[keyof typeof FramingAction];
+
+/** How far one press moves or zooms. */
+interface PhotoFramingSteps {
+    /** Nudge per press, % of the card. */
+    offsetPct: number;
+    /** Zoom per press, as a scale delta. */
+    scale: number;
+}
+declare const PHOTO_FRAMING_STEPS: PhotoFramingSteps;
+/**
+ * Applies one control press. The result is always clamped and rounded, so ten
+ * presses of +0.1 land on exactly 2, not 1.9999999999999998.
+ */
+declare function stepFraming(current: PhotoFramingInput | null | undefined, action: FramingAction, steps?: PhotoFramingSteps): PhotoFraming;
+/** False when the press would change nothing (at a bound, or reset on the default). */
+declare function canStepFraming(current: PhotoFramingInput | null | undefined, action: FramingAction, steps?: PhotoFramingSteps): boolean;
+
+export { DEFAULT_PHOTO_FRAMING, FramingAction, PHOTO_FRAMING_BOUNDS, PHOTO_FRAMING_STEPS, type PhotoFraming, type PhotoFramingInput, type PhotoFramingSteps, type PhotoFramingTransform, canStepFraming, clampFraming, framingToTransform, isDefaultFraming, stepFraming };

package/dist/framing.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Photo framing: the `{x, y, scale}` an organiser sets on a performer card.
+ *
+ * The bounds MIRROR `kefi-landings/src/lib/config-to-site.ts` (`photoTransform`,
+ * MAX_PHOTO_OFFSET_PCT / MIN_PHOTO_SCALE / MAX_PHOTO_SCALE), which is what the
+ * public landing page renders. The editor must never offer a value the landing
+ * page would silently clamp away, so the numbers here and there must stay equal.
+ * KEFI-PEOPLE-1 T12 "import the bounds instead of hard-coding them" removes the copy.
+ *
+ * This file imports nothing: it backs the framework-free `@dloizides/ui-media/framing`
+ * subpath.
+ */
+/** A framing value after clamping: every field finite and inside the bounds. */
+interface PhotoFraming {
+    /** Horizontal nudge, % of the card. Negative = left. */
+    readonly x: number;
+    /** Vertical nudge, % of the card. Negative = up. */
+    readonly y: number;
+    /** Zoom factor. 1 = the photo's natural cover fit. */
+    readonly scale: number;
+}
+/** What config / an API may hold: any field missing, null or non-finite. */
+interface PhotoFramingInput {
+    x?: number | null;
+    y?: number | null;
+    scale?: number | null;
+}
+declare const PHOTO_FRAMING_BOUNDS: Readonly<{
+    /** Widest nudge, as a percentage of the card, in either direction. */
+    maxOffsetPct: 60;
+    /** Below 1 the photo shrinks inside an already-roomy frame. */
+    minScale: 0.5;
+    /** Far above 2 the subject's head leaves the card entirely. */
+    maxScale: 3;
+}>;
+declare const DEFAULT_PHOTO_FRAMING: PhotoFraming;
+/**
+ * Normalises any stored framing: non-finite fields fall back to the default,
+ * the rest are clamped to {@link PHOTO_FRAMING_BOUNDS}. Same rules as the
+ * landing page's `photoTransform`, so what the editor previews is what ships.
+ */
+declare function clampFraming(input?: PhotoFramingInput | null): PhotoFraming;
+/** True when the framing is the identity (the landing page emits no transform). */
+declare const isDefaultFraming: (framing: PhotoFraming) => boolean;
+/**
+ * An RN `transform` array. Percent translates are relative to the element
+ * itself on RN-web, matching the landing page's CSS `translate(x%, y%) scale(s)`.
+ * Typed locally so this module stays free of a react-native import.
+ */
+type PhotoFramingTransform = [
+    {
+        translateX: `${number}%`;
+    },
+    {
+        translateY: `${number}%`;
+    },
+    {
+        scale: number;
+    }
+];
+declare const framingToTransform: (framing: PhotoFraming) => PhotoFramingTransform;
+
+/**
+ * The seven controls of the framing editor. An `as const` object rather than a
+ * TS `const enum`: a const enum shipped in a .d.ts cannot be read by consumers
+ * compiled with `isolatedModules` (every Expo / Babel portal).
+ */
+declare const FramingAction: {
+    readonly ZoomIn: "zoomIn";
+    readonly ZoomOut: "zoomOut";
+    readonly MoveUp: "moveUp";
+    readonly MoveDown: "moveDown";
+    readonly MoveLeft: "moveLeft";
+    readonly MoveRight: "moveRight";
+    readonly Reset: "reset";
+};
+type FramingAction = (typeof FramingAction)[keyof typeof FramingAction];
+
+/** How far one press moves or zooms. */
+interface PhotoFramingSteps {
+    /** Nudge per press, % of the card. */
+    offsetPct: number;
+    /** Zoom per press, as a scale delta. */
+    scale: number;
+}
+declare const PHOTO_FRAMING_STEPS: PhotoFramingSteps;
+/**
+ * Applies one control press. The result is always clamped and rounded, so ten
+ * presses of +0.1 land on exactly 2, not 1.9999999999999998.
+ */
+declare function stepFraming(current: PhotoFramingInput | null | undefined, action: FramingAction, steps?: PhotoFramingSteps): PhotoFraming;
+/** False when the press would change nothing (at a bound, or reset on the default). */
+declare function canStepFraming(current: PhotoFramingInput | null | undefined, action: FramingAction, steps?: PhotoFramingSteps): boolean;
+
+export { DEFAULT_PHOTO_FRAMING, FramingAction, PHOTO_FRAMING_BOUNDS, PHOTO_FRAMING_STEPS, type PhotoFraming, type PhotoFramingInput, type PhotoFramingSteps, type PhotoFramingTransform, canStepFraming, clampFraming, framingToTransform, isDefaultFraming, stepFraming };

package/dist/framing.js

@@ -0,0 +1,80 @@
+'use strict';
+
+// src/framing/photoFraming.ts
+var PHOTO_FRAMING_BOUNDS = Object.freeze({
+  /** Widest nudge, as a percentage of the card, in either direction. */
+  maxOffsetPct: 60,
+  /** Below 1 the photo shrinks inside an already-roomy frame. */
+  minScale: 0.5,
+  /** Far above 2 the subject's head leaves the card entirely. */
+  maxScale: 3
+});
+var DEFAULT_PHOTO_FRAMING = Object.freeze({ x: 0, y: 0, scale: 1 });
+var clamp = (value, min, max) => Math.min(max, Math.max(min, value));
+var finiteOr = (value, fallback) => typeof value === "number" && Number.isFinite(value) ? value : fallback;
+function clampFraming(input) {
+  if (!input) return DEFAULT_PHOTO_FRAMING;
+  const { maxOffsetPct, minScale, maxScale } = PHOTO_FRAMING_BOUNDS;
+  return {
+    x: clamp(finiteOr(input.x, DEFAULT_PHOTO_FRAMING.x), -maxOffsetPct, maxOffsetPct),
+    y: clamp(finiteOr(input.y, DEFAULT_PHOTO_FRAMING.y), -maxOffsetPct, maxOffsetPct),
+    scale: clamp(finiteOr(input.scale, DEFAULT_PHOTO_FRAMING.scale), minScale, maxScale)
+  };
+}
+var isDefaultFraming = (framing) => framing.x === DEFAULT_PHOTO_FRAMING.x && framing.y === DEFAULT_PHOTO_FRAMING.y && framing.scale === DEFAULT_PHOTO_FRAMING.scale;
+var framingToTransform = (framing) => [
+  { translateX: `${framing.x}%` },
+  { translateY: `${framing.y}%` },
+  { scale: framing.scale }
+];
+
+// src/framing/FramingAction.ts
+var FramingAction = {
+  ZoomIn: "zoomIn",
+  ZoomOut: "zoomOut",
+  MoveUp: "moveUp",
+  MoveDown: "moveDown",
+  MoveLeft: "moveLeft",
+  MoveRight: "moveRight",
+  Reset: "reset"
+};
+
+// src/framing/stepFraming.ts
+var PHOTO_FRAMING_STEPS = Object.freeze({ offsetPct: 5, scale: 0.1 });
+var PRECISION = 1e3;
+var round = (n) => Math.round(n * PRECISION) / PRECISION;
+var DIRECTIONS = {
+  [FramingAction.ZoomIn]: [0, 0, 1],
+  [FramingAction.ZoomOut]: [0, 0, -1],
+  [FramingAction.MoveUp]: [0, -1, 0],
+  [FramingAction.MoveDown]: [0, 1, 0],
+  [FramingAction.MoveLeft]: [-1, 0, 0],
+  [FramingAction.MoveRight]: [1, 0, 0]
+};
+function stepFraming(current, action, steps = PHOTO_FRAMING_STEPS) {
+  if (action === FramingAction.Reset) return DEFAULT_PHOTO_FRAMING;
+  const base = clampFraming(current);
+  const [dx, dy, ds] = DIRECTIONS[action];
+  return clampFraming({
+    x: round(base.x + dx * steps.offsetPct),
+    y: round(base.y + dy * steps.offsetPct),
+    scale: round(base.scale + ds * steps.scale)
+  });
+}
+function canStepFraming(current, action, steps = PHOTO_FRAMING_STEPS) {
+  const base = clampFraming(current);
+  const next = stepFraming(base, action, steps);
+  return next.x !== base.x || next.y !== base.y || next.scale !== base.scale;
+}
+
+exports.DEFAULT_PHOTO_FRAMING = DEFAULT_PHOTO_FRAMING;
+exports.FramingAction = FramingAction;
+exports.PHOTO_FRAMING_BOUNDS = PHOTO_FRAMING_BOUNDS;
+exports.PHOTO_FRAMING_STEPS = PHOTO_FRAMING_STEPS;
+exports.canStepFraming = canStepFraming;
+exports.clampFraming = clampFraming;
+exports.framingToTransform = framingToTransform;
+exports.isDefaultFraming = isDefaultFraming;
+exports.stepFraming = stepFraming;
+//# sourceMappingURL=framing.js.map
+//# sourceMappingURL=framing.js.map

package/dist/framing.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/framing/photoFraming.ts","../src/framing/FramingAction.ts","../src/framing/stepFraming.ts"],"names":[],"mappings":"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","file":"framing.js","sourcesContent":["/**\n * Photo framing: the `{x, y, scale}` an organiser sets on a performer card.\n *\n * The bounds MIRROR `kefi-landings/src/lib/config-to-site.ts` (`photoTransform`,\n * MAX_PHOTO_OFFSET_PCT / MIN_PHOTO_SCALE / MAX_PHOTO_SCALE), which is what the\n * public landing page renders. The editor must never offer a value the landing\n * page would silently clamp away, so the numbers here and there must stay equal.\n * KEFI-PEOPLE-1 T12 \"import the bounds instead of hard-coding them\" removes the copy.\n *\n * This file imports nothing: it backs the framework-free `@dloizides/ui-media/framing`\n * subpath.\n */\n\n/** A framing value after clamping: every field finite and inside the bounds. */\nexport interface PhotoFraming {\n  /** Horizontal nudge, % of the card. Negative = left. */\n  readonly x: number;\n  /** Vertical nudge, % of the card. Negative = up. */\n  readonly y: number;\n  /** Zoom factor. 1 = the photo's natural cover fit. */\n  readonly scale: number;\n}\n\n/** What config / an API may hold: any field missing, null or non-finite. */\nexport interface PhotoFramingInput {\n  x?: number | null;\n  y?: number | null;\n  scale?: number | null;\n}\n\nexport const PHOTO_FRAMING_BOUNDS = Object.freeze({\n  /** Widest nudge, as a percentage of the card, in either direction. */\n  maxOffsetPct: 60,\n  /** Below 1 the photo shrinks inside an already-roomy frame. */\n  minScale: 0.5,\n  /** Far above 2 the subject's head leaves the card entirely. */\n  maxScale: 3,\n});\n\nexport const DEFAULT_PHOTO_FRAMING: PhotoFraming = Object.freeze({ x: 0, y: 0, scale: 1 });\n\nconst clamp = (value: number, min: number, max: number): number => Math.min(max, Math.max(min, value));\n\nconst finiteOr = (value: number | null | undefined, fallback: number): number =>\n  typeof value === 'number' && Number.isFinite(value) ? value : fallback;\n\n/**\n * Normalises any stored framing: non-finite fields fall back to the default,\n * the rest are clamped to {@link PHOTO_FRAMING_BOUNDS}. Same rules as the\n * landing page's `photoTransform`, so what the editor previews is what ships.\n */\nexport function clampFraming(input?: PhotoFramingInput | null): PhotoFraming {\n  if (!input) return DEFAULT_PHOTO_FRAMING;\n  const { maxOffsetPct, minScale, maxScale } = PHOTO_FRAMING_BOUNDS;\n  return {\n    x: clamp(finiteOr(input.x, DEFAULT_PHOTO_FRAMING.x), -maxOffsetPct, maxOffsetPct),\n    y: clamp(finiteOr(input.y, DEFAULT_PHOTO_FRAMING.y), -maxOffsetPct, maxOffsetPct),\n    scale: clamp(finiteOr(input.scale, DEFAULT_PHOTO_FRAMING.scale), minScale, maxScale),\n  };\n}\n\n/** True when the framing is the identity (the landing page emits no transform). */\nexport const isDefaultFraming = (framing: PhotoFraming): boolean =>\n  framing.x === DEFAULT_PHOTO_FRAMING.x &&\n  framing.y === DEFAULT_PHOTO_FRAMING.y &&\n  framing.scale === DEFAULT_PHOTO_FRAMING.scale;\n\n/**\n * An RN `transform` array. Percent translates are relative to the element\n * itself on RN-web, matching the landing page's CSS `translate(x%, y%) scale(s)`.\n * Typed locally so this module stays free of a react-native import.\n */\nexport type PhotoFramingTransform = [\n  { translateX: `${number}%` },\n  { translateY: `${number}%` },\n  { scale: number },\n];\n\nexport const framingToTransform = (framing: PhotoFraming): PhotoFramingTransform => [\n  { translateX: `${framing.x}%` },\n  { translateY: `${framing.y}%` },\n  { scale: framing.scale },\n];\n","/**\n * The seven controls of the framing editor. An `as const` object rather than a\n * TS `const enum`: a const enum shipped in a .d.ts cannot be read by consumers\n * compiled with `isolatedModules` (every Expo / Babel portal).\n */\nexport const FramingAction = {\n  ZoomIn: 'zoomIn',\n  ZoomOut: 'zoomOut',\n  MoveUp: 'moveUp',\n  MoveDown: 'moveDown',\n  MoveLeft: 'moveLeft',\n  MoveRight: 'moveRight',\n  Reset: 'reset',\n} as const;\n\nexport type FramingAction = (typeof FramingAction)[keyof typeof FramingAction];\n","import { FramingAction } from './FramingAction';\nimport type { PhotoFraming, PhotoFramingInput } from './photoFraming';\nimport { DEFAULT_PHOTO_FRAMING, clampFraming } from './photoFraming';\n\n/** How far one press moves or zooms. */\nexport interface PhotoFramingSteps {\n  /** Nudge per press, % of the card. */\n  offsetPct: number;\n  /** Zoom per press, as a scale delta. */\n  scale: number;\n}\n\nexport const PHOTO_FRAMING_STEPS: PhotoFramingSteps = Object.freeze({ offsetPct: 5, scale: 0.1 });\n\n/** Three decimals, the same precision the landing page writes into its CSS. */\nconst PRECISION = 1000;\nconst round = (n: number): number => Math.round(n * PRECISION) / PRECISION;\n\ntype MoveAction = Exclude<FramingAction, typeof FramingAction.Reset>;\n\n/** [x, y, scale] direction of each non-reset action. */\nconst DIRECTIONS: Record<MoveAction, readonly [number, number, number]> = {\n  [FramingAction.ZoomIn]: [0, 0, 1],\n  [FramingAction.ZoomOut]: [0, 0, -1],\n  [FramingAction.MoveUp]: [0, -1, 0],\n  [FramingAction.MoveDown]: [0, 1, 0],\n  [FramingAction.MoveLeft]: [-1, 0, 0],\n  [FramingAction.MoveRight]: [1, 0, 0],\n};\n\n/**\n * Applies one control press. The result is always clamped and rounded, so ten\n * presses of +0.1 land on exactly 2, not 1.9999999999999998.\n */\nexport function stepFraming(\n  current: PhotoFramingInput | null | undefined,\n  action: FramingAction,\n  steps: PhotoFramingSteps = PHOTO_FRAMING_STEPS,\n): PhotoFraming {\n  if (action === FramingAction.Reset) return DEFAULT_PHOTO_FRAMING;\n  const base = clampFraming(current);\n  const [dx, dy, ds] = DIRECTIONS[action];\n  return clampFraming({\n    x: round(base.x + dx * steps.offsetPct),\n    y: round(base.y + dy * steps.offsetPct),\n    scale: round(base.scale + ds * steps.scale),\n  });\n}\n\n/** False when the press would change nothing (at a bound, or reset on the default). */\nexport function canStepFraming(\n  current: PhotoFramingInput | null | undefined,\n  action: FramingAction,\n  steps: PhotoFramingSteps = PHOTO_FRAMING_STEPS,\n): boolean {\n  const base = clampFraming(current);\n  const next = stepFraming(base, action, steps);\n  return next.x !== base.x || next.y !== base.y || next.scale !== base.scale;\n}\n"]}

package/dist/framing.mjs

@@ -0,0 +1,70 @@
+// src/framing/photoFraming.ts
+var PHOTO_FRAMING_BOUNDS = Object.freeze({
+  /** Widest nudge, as a percentage of the card, in either direction. */
+  maxOffsetPct: 60,
+  /** Below 1 the photo shrinks inside an already-roomy frame. */
+  minScale: 0.5,
+  /** Far above 2 the subject's head leaves the card entirely. */
+  maxScale: 3
+});
+var DEFAULT_PHOTO_FRAMING = Object.freeze({ x: 0, y: 0, scale: 1 });
+var clamp = (value, min, max) => Math.min(max, Math.max(min, value));
+var finiteOr = (value, fallback) => typeof value === "number" && Number.isFinite(value) ? value : fallback;
+function clampFraming(input) {
+  if (!input) return DEFAULT_PHOTO_FRAMING;
+  const { maxOffsetPct, minScale, maxScale } = PHOTO_FRAMING_BOUNDS;
+  return {
+    x: clamp(finiteOr(input.x, DEFAULT_PHOTO_FRAMING.x), -maxOffsetPct, maxOffsetPct),
+    y: clamp(finiteOr(input.y, DEFAULT_PHOTO_FRAMING.y), -maxOffsetPct, maxOffsetPct),
+    scale: clamp(finiteOr(input.scale, DEFAULT_PHOTO_FRAMING.scale), minScale, maxScale)
+  };
+}
+var isDefaultFraming = (framing) => framing.x === DEFAULT_PHOTO_FRAMING.x && framing.y === DEFAULT_PHOTO_FRAMING.y && framing.scale === DEFAULT_PHOTO_FRAMING.scale;
+var framingToTransform = (framing) => [
+  { translateX: `${framing.x}%` },
+  { translateY: `${framing.y}%` },
+  { scale: framing.scale }
+];
+
+// src/framing/FramingAction.ts
+var FramingAction = {
+  ZoomIn: "zoomIn",
+  ZoomOut: "zoomOut",
+  MoveUp: "moveUp",
+  MoveDown: "moveDown",
+  MoveLeft: "moveLeft",
+  MoveRight: "moveRight",
+  Reset: "reset"
+};
+
+// src/framing/stepFraming.ts
+var PHOTO_FRAMING_STEPS = Object.freeze({ offsetPct: 5, scale: 0.1 });
+var PRECISION = 1e3;
+var round = (n) => Math.round(n * PRECISION) / PRECISION;
+var DIRECTIONS = {
+  [FramingAction.ZoomIn]: [0, 0, 1],
+  [FramingAction.ZoomOut]: [0, 0, -1],
+  [FramingAction.MoveUp]: [0, -1, 0],
+  [FramingAction.MoveDown]: [0, 1, 0],
+  [FramingAction.MoveLeft]: [-1, 0, 0],
+  [FramingAction.MoveRight]: [1, 0, 0]
+};
+function stepFraming(current, action, steps = PHOTO_FRAMING_STEPS) {
+  if (action === FramingAction.Reset) return DEFAULT_PHOTO_FRAMING;
+  const base = clampFraming(current);
+  const [dx, dy, ds] = DIRECTIONS[action];
+  return clampFraming({
+    x: round(base.x + dx * steps.offsetPct),
+    y: round(base.y + dy * steps.offsetPct),
+    scale: round(base.scale + ds * steps.scale)
+  });
+}
+function canStepFraming(current, action, steps = PHOTO_FRAMING_STEPS) {
+  const base = clampFraming(current);
+  const next = stepFraming(base, action, steps);
+  return next.x !== base.x || next.y !== base.y || next.scale !== base.scale;
+}
+
+export { DEFAULT_PHOTO_FRAMING, FramingAction, PHOTO_FRAMING_BOUNDS, PHOTO_FRAMING_STEPS, canStepFraming, clampFraming, framingToTransform, isDefaultFraming, stepFraming };
+//# sourceMappingURL=framing.mjs.map
+//# sourceMappingURL=framing.mjs.map

package/dist/framing.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/framing/photoFraming.ts","../src/framing/FramingAction.ts","../src/framing/stepFraming.ts"],"names":[],"mappings":"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","file":"framing.mjs","sourcesContent":["/**\n * Photo framing: the `{x, y, scale}` an organiser sets on a performer card.\n *\n * The bounds MIRROR `kefi-landings/src/lib/config-to-site.ts` (`photoTransform`,\n * MAX_PHOTO_OFFSET_PCT / MIN_PHOTO_SCALE / MAX_PHOTO_SCALE), which is what the\n * public landing page renders. The editor must never offer a value the landing\n * page would silently clamp away, so the numbers here and there must stay equal.\n * KEFI-PEOPLE-1 T12 \"import the bounds instead of hard-coding them\" removes the copy.\n *\n * This file imports nothing: it backs the framework-free `@dloizides/ui-media/framing`\n * subpath.\n */\n\n/** A framing value after clamping: every field finite and inside the bounds. */\nexport interface PhotoFraming {\n  /** Horizontal nudge, % of the card. Negative = left. */\n  readonly x: number;\n  /** Vertical nudge, % of the card. Negative = up. */\n  readonly y: number;\n  /** Zoom factor. 1 = the photo's natural cover fit. */\n  readonly scale: number;\n}\n\n/** What config / an API may hold: any field missing, null or non-finite. */\nexport interface PhotoFramingInput {\n  x?: number | null;\n  y?: number | null;\n  scale?: number | null;\n}\n\nexport const PHOTO_FRAMING_BOUNDS = Object.freeze({\n  /** Widest nudge, as a percentage of the card, in either direction. */\n  maxOffsetPct: 60,\n  /** Below 1 the photo shrinks inside an already-roomy frame. */\n  minScale: 0.5,\n  /** Far above 2 the subject's head leaves the card entirely. */\n  maxScale: 3,\n});\n\nexport const DEFAULT_PHOTO_FRAMING: PhotoFraming = Object.freeze({ x: 0, y: 0, scale: 1 });\n\nconst clamp = (value: number, min: number, max: number): number => Math.min(max, Math.max(min, value));\n\nconst finiteOr = (value: number | null | undefined, fallback: number): number =>\n  typeof value === 'number' && Number.isFinite(value) ? value : fallback;\n\n/**\n * Normalises any stored framing: non-finite fields fall back to the default,\n * the rest are clamped to {@link PHOTO_FRAMING_BOUNDS}. Same rules as the\n * landing page's `photoTransform`, so what the editor previews is what ships.\n */\nexport function clampFraming(input?: PhotoFramingInput | null): PhotoFraming {\n  if (!input) return DEFAULT_PHOTO_FRAMING;\n  const { maxOffsetPct, minScale, maxScale } = PHOTO_FRAMING_BOUNDS;\n  return {\n    x: clamp(finiteOr(input.x, DEFAULT_PHOTO_FRAMING.x), -maxOffsetPct, maxOffsetPct),\n    y: clamp(finiteOr(input.y, DEFAULT_PHOTO_FRAMING.y), -maxOffsetPct, maxOffsetPct),\n    scale: clamp(finiteOr(input.scale, DEFAULT_PHOTO_FRAMING.scale), minScale, maxScale),\n  };\n}\n\n/** True when the framing is the identity (the landing page emits no transform). */\nexport const isDefaultFraming = (framing: PhotoFraming): boolean =>\n  framing.x === DEFAULT_PHOTO_FRAMING.x &&\n  framing.y === DEFAULT_PHOTO_FRAMING.y &&\n  framing.scale === DEFAULT_PHOTO_FRAMING.scale;\n\n/**\n * An RN `transform` array. Percent translates are relative to the element\n * itself on RN-web, matching the landing page's CSS `translate(x%, y%) scale(s)`.\n * Typed locally so this module stays free of a react-native import.\n */\nexport type PhotoFramingTransform = [\n  { translateX: `${number}%` },\n  { translateY: `${number}%` },\n  { scale: number },\n];\n\nexport const framingToTransform = (framing: PhotoFraming): PhotoFramingTransform => [\n  { translateX: `${framing.x}%` },\n  { translateY: `${framing.y}%` },\n  { scale: framing.scale },\n];\n","/**\n * The seven controls of the framing editor. An `as const` object rather than a\n * TS `const enum`: a const enum shipped in a .d.ts cannot be read by consumers\n * compiled with `isolatedModules` (every Expo / Babel portal).\n */\nexport const FramingAction = {\n  ZoomIn: 'zoomIn',\n  ZoomOut: 'zoomOut',\n  MoveUp: 'moveUp',\n  MoveDown: 'moveDown',\n  MoveLeft: 'moveLeft',\n  MoveRight: 'moveRight',\n  Reset: 'reset',\n} as const;\n\nexport type FramingAction = (typeof FramingAction)[keyof typeof FramingAction];\n","import { FramingAction } from './FramingAction';\nimport type { PhotoFraming, PhotoFramingInput } from './photoFraming';\nimport { DEFAULT_PHOTO_FRAMING, clampFraming } from './photoFraming';\n\n/** How far one press moves or zooms. */\nexport interface PhotoFramingSteps {\n  /** Nudge per press, % of the card. */\n  offsetPct: number;\n  /** Zoom per press, as a scale delta. */\n  scale: number;\n}\n\nexport const PHOTO_FRAMING_STEPS: PhotoFramingSteps = Object.freeze({ offsetPct: 5, scale: 0.1 });\n\n/** Three decimals, the same precision the landing page writes into its CSS. */\nconst PRECISION = 1000;\nconst round = (n: number): number => Math.round(n * PRECISION) / PRECISION;\n\ntype MoveAction = Exclude<FramingAction, typeof FramingAction.Reset>;\n\n/** [x, y, scale] direction of each non-reset action. */\nconst DIRECTIONS: Record<MoveAction, readonly [number, number, number]> = {\n  [FramingAction.ZoomIn]: [0, 0, 1],\n  [FramingAction.ZoomOut]: [0, 0, -1],\n  [FramingAction.MoveUp]: [0, -1, 0],\n  [FramingAction.MoveDown]: [0, 1, 0],\n  [FramingAction.MoveLeft]: [-1, 0, 0],\n  [FramingAction.MoveRight]: [1, 0, 0],\n};\n\n/**\n * Applies one control press. The result is always clamped and rounded, so ten\n * presses of +0.1 land on exactly 2, not 1.9999999999999998.\n */\nexport function stepFraming(\n  current: PhotoFramingInput | null | undefined,\n  action: FramingAction,\n  steps: PhotoFramingSteps = PHOTO_FRAMING_STEPS,\n): PhotoFraming {\n  if (action === FramingAction.Reset) return DEFAULT_PHOTO_FRAMING;\n  const base = clampFraming(current);\n  const [dx, dy, ds] = DIRECTIONS[action];\n  return clampFraming({\n    x: round(base.x + dx * steps.offsetPct),\n    y: round(base.y + dy * steps.offsetPct),\n    scale: round(base.scale + ds * steps.scale),\n  });\n}\n\n/** False when the press would change nothing (at a bound, or reset on the default). */\nexport function canStepFraming(\n  current: PhotoFramingInput | null | undefined,\n  action: FramingAction,\n  steps: PhotoFramingSteps = PHOTO_FRAMING_STEPS,\n): boolean {\n  const base = clampFraming(current);\n  const next = stepFraming(base, action, steps);\n  return next.x !== base.x || next.y !== base.y || next.scale !== base.scale;\n}\n"]}

package/dist/index.d.mts

@@ -0,0 +1,143 @@
+import { PhotoFramingInput, PhotoFraming, PhotoFramingTransform, FramingAction, PhotoFramingSteps } from './framing.mjs';
+export { DEFAULT_PHOTO_FRAMING, PHOTO_FRAMING_BOUNDS, PHOTO_FRAMING_STEPS, canStepFraming, clampFraming, framingToTransform, isDefaultFraming, stepFraming } from './framing.mjs';
+import React from 'react';
+import { ButtonVariant } from '@dloizides/ui-buttons';
+
+/**
+ * The four states of an image upload slot (KEFI-PEOPLE-1 design board "upload
+ * slot"). An `as const` object, not a `const enum`, so Babel / isolatedModules
+ * consumers can read it from the published .d.ts.
+ */
+declare const ImagePickerStatus: {
+    readonly Idle: "idle";
+    readonly Uploading: "uploading";
+    readonly Error: "error";
+    readonly Done: "done";
+};
+type ImagePickerStatus = (typeof ImagePickerStatus)[keyof typeof ImagePickerStatus];
+
+/**
+ * ImagePickerButton — one upload slot: pick an image, hand it to the consumer's
+ * `upload` function, show idle / uploading / error / done.
+ *
+ * No network code and no copy of its own: the transport is a prop and every
+ * string arrives through `labels`, so each portal passes its FM() keys.
+ */
+
+interface ImagePickerLabels {
+    /** Button, idle: "Add photo". */
+    pick: string;
+    /** Button, uploading: "Uploading...". */
+    uploading: string;
+    /** Button, done: "Replace photo". */
+    replace: string;
+    /** Button, error: "Try again". */
+    retry: string;
+    /** Status line after a successful upload: "Photo saved". */
+    done: string;
+    /** Status line after a failure: "Upload failed". */
+    error: string;
+    /** Accessibility hint for the button: "Opens a file picker to choose an image". */
+    hint: string;
+}
+interface ImagePickerButtonProps<TFile = File> {
+    upload: (file: TFile) => Promise<void>;
+    labels: ImagePickerLabels;
+    testID: string;
+    /** Defaults to the browser file dialog. Native consumers pass their own picker. */
+    pickFile?: () => Promise<TFile | null>;
+    /** `accept` for the default web picker. Default `image/*`. */
+    accept?: string;
+    /** Start in the `done` state (the slot already has an image). */
+    hasImage?: boolean;
+    onError?: (error: unknown) => void;
+    disabled?: boolean;
+}
+interface PickerView {
+    buttonLabel: string;
+    variant: ButtonVariant;
+    statusText: string | null;
+    /** Paint the status line in the theme's error colour. */
+    isError: boolean;
+}
+/** Pure status -> copy/variant mapping (unit-tested; the component only paints it). */
+declare function resolvePickerView(status: ImagePickerStatus, labels: ImagePickerLabels): PickerView;
+declare function ImagePickerButton<TFile = File>({ upload, labels, testID, pickFile, accept, hasImage, onError, disabled, }: ImagePickerButtonProps<TFile>): React.ReactElement;
+
+declare const DEFAULT_IMAGE_ACCEPT = "image/*";
+/**
+ * Opens the browser's file dialog for ONE file. Resolves `null` on cancel, and
+ * where there is no DOM (native) — a native consumer passes its own `pickFile`.
+ */
+declare function pickWebImage(accept?: string): Promise<File | null>;
+interface UseImageUploadOptions<TFile> {
+    /** Consumer-owned transport. Resolve = stored; reject = error state. No network code lives here. */
+    upload: (file: TFile) => Promise<void>;
+    /** Picks one file; `null` means the user cancelled. */
+    pickFile: () => Promise<TFile | null>;
+    /** Start in `done` when the slot already holds an image. */
+    hasImage?: boolean;
+    /** Told about a failed pick or upload (logging / toasts). */
+    onError?: (error: unknown) => void;
+}
+interface ImageUploadState {
+    status: ImagePickerStatus;
+    /** Pick then upload. A second call while one is in flight is ignored. */
+    pick: () => Promise<void>;
+}
+/**
+ * The upload slot's state machine: idle -> uploading -> done | error, and from
+ * done or error back to uploading on the next pick. A cancelled pick leaves the
+ * state as it was, so cancelling "Replace" does not wipe a finished upload.
+ */
+declare function useImageUpload<TFile>({ upload, pickFile, hasImage, onError, }: UseImageUploadOptions<TFile>): ImageUploadState;
+
+/** Name + hint of one control. `label` is the full phrase ("Move photo up"). */
+interface FramingActionLabel {
+    label: string;
+    hint: string;
+}
+/** Every string the editor shows. The package has no copy of its own (FM-free). */
+interface PhotoFramingLabels {
+    /** Heading over the zoom stepper: "Size". */
+    size: string;
+    /** Heading over the d-pad: "Position". */
+    position: string;
+    /** Readout between the zoom buttons, given a whole percent: (120) => "120%". */
+    scaleValue: (percent: number) => string;
+    actions: Record<FramingAction, FramingActionLabel>;
+}
+interface PhotoFramingPreviewArgs {
+    /** The clamped value. */
+    framing: PhotoFraming;
+    /** Ready to spread onto the photo: `style={{ transform }}`. */
+    transform: PhotoFramingTransform;
+}
+interface PhotoFramingEditorProps {
+    /** Stored framing; clamped before use, so raw config is safe to pass. */
+    value: PhotoFramingInput | null | undefined;
+    /** Receives the next clamped value after each press. */
+    onChange: (next: PhotoFraming) => void;
+    /** Renders the consumer's own card with the photo transformed — a live preview. */
+    renderPreview: (args: PhotoFramingPreviewArgs) => React.ReactNode;
+    labels: PhotoFramingLabels;
+    testID: string;
+    steps?: PhotoFramingSteps;
+    /** Override the default arrow / plus / minus glyphs (e.g. with ui-icons). */
+    renderGlyph?: (action: FramingAction, color: string, size: number) => React.ReactNode;
+    disabled?: boolean;
+}
+
+/**
+ * PhotoFramingEditor — the KEFI-PEOPLE-1 "A2" framing screen: a live preview of
+ * the consumer's own card (render prop) beside a zoom stepper and a position
+ * d-pad. The value is `{x, y, scale}`, clamped to PHOTO_FRAMING_BOUNDS, the same
+ * rules the public landing page applies — the preview is what ships.
+ *
+ * Narrow first: preview stacked over the controls; from ui-layout's
+ * LAYOUT_COLLAPSE_BREAKPOINT up they sit side by side.
+ */
+
+declare const PhotoFramingEditor: ({ value, onChange, renderPreview, labels, testID, steps, renderGlyph, disabled, }: PhotoFramingEditorProps) => React.ReactElement;
+
+export { DEFAULT_IMAGE_ACCEPT, FramingAction, type FramingActionLabel, ImagePickerButton, type ImagePickerButtonProps, type ImagePickerLabels, ImagePickerStatus, type ImageUploadState, PhotoFraming, PhotoFramingEditor, type PhotoFramingEditorProps, PhotoFramingInput, type PhotoFramingLabels, type PhotoFramingPreviewArgs, PhotoFramingSteps, PhotoFramingTransform, type PickerView, type UseImageUploadOptions, pickWebImage, resolvePickerView, useImageUpload };