flet-box 0.0.0-stage → 1.0.2

package/src/utils/composeUpdate.js

@@ -0,0 +1,65 @@
+/**
+ * @file composeUpdate.js
+ * @description
+ * Composes a widget's own prop-application logic with the factory's reactive
+ * `update` instead of overwriting it.
+ *
+ * Widgets such as Accordion, Slider and Dropdown keep widget state (currentValue,
+ * currentOptions, …) in a closure and need a bespoke `update` to apply it. The
+ * naive implementation `container.update = update` destroys the factory's update,
+ * which re-applies styles, events, effects and children — so generic calls like
+ * `slider.update({ opacity: .5 })` silently stopped working.
+ *
+ * `composeUpdate` splits every `update(newProps)` call in two:
+ *  - keys owned by the widget (the `widgetPropKeys` set) → `applyWidgetProps`
+ *  - everything else → the factory's original `update`
+ *
+ * Widget-owned keys are also stripped from `_originalProps`, because the factory
+ * merges them back on every update: a stale construction-time value (say
+ * `border: "1px solid red"`) would be re-applied as a style and silently clobber
+ * a later widget-level change of the same prop.
+ *
+ * @module composeUpdate
+ */
+
+/**
+ * Wires `container.update` so widget props and factory props coexist.
+ *
+ * @param {HTMLElement} container - The widget root returned by `WidgetFactory`.
+ * @param {Iterable<string>} widgetPropKeys - Prop names owned by the widget.
+ *   These are routed to `applyWidgetProps` and never reach the factory.
+ * @param {function(Object): void} applyWidgetProps - The widget's own prop
+ *   application logic. It receives only widget-owned keys and may ignore keys it
+ *   does not handle (preserving each widget's existing behavior).
+ * @returns {HTMLElement} The same container, for chaining.
+ */
+export function composeUpdate(container, widgetPropKeys, applyWidgetProps) {
+  const widgetKeys = new Set(widgetPropKeys);
+  const factoryUpdate = container.update;
+
+  // The factory re-processes `_originalProps` on every update; widget-owned keys
+  // must not live there or they would be re-applied as styles/attributes from
+  // their construction-time values.
+  if (container._originalProps) {
+    for (const key of widgetKeys) delete container._originalProps[key];
+  }
+
+  container.update = (newProps = {}) => {
+    const widgetProps = {};
+    const factoryProps = {};
+    for (const key of Object.keys(newProps)) {
+      if (widgetKeys.has(key)) widgetProps[key] = newProps[key];
+      else factoryProps[key] = newProps[key];
+    }
+
+    applyWidgetProps(widgetProps);
+
+    if (Object.keys(factoryProps).length > 0) factoryUpdate(factoryProps);
+
+    return container;
+  };
+
+  return container;
+}
+
+export default composeUpdate;

package/src/utils/getWidgetProps.js

@@ -0,0 +1,35 @@
+// utils/getWidgetProps.js
+
+/**
+ * Gets the current props of a widget
+ * @param {HTMLElement} widget - The widget to inspect
+ * @returns {Object} Dictionary with the widget's props
+ *
+ * @example
+ * const props = getWidgetProps(myButton);
+ * // { text: 'Click', variant: 'filled', color: '#007aff' }
+ */
+export const getWidgetProps = (widget) => {
+  return { ...(widget._props || {}) };
+};
+
+/**
+ * Gets a specific prop from a widget
+ * @param {HTMLElement} widget - The widget to inspect
+ * @param {string} propName - Name of the prop
+ * @returns {any} Prop value or undefined
+ */
+export const getWidgetProp = (widget, propName) => {
+  return widget._props ? widget._props[propName] : undefined;
+};
+
+/**
+ * Gets all props as a formatted string
+ * @param {HTMLElement} widget - The widget to inspect
+ * @returns {string} Formatted props string
+ */
+export const stringifyWidgetProps = (widget) => {
+  return JSON.stringify(widget._props || {}, null, 2);
+};
+
+export default { getWidgetProps, getWidgetProp, stringifyWidgetProps };

package/src/utils/index.js

@@ -0,0 +1,76 @@
+// src/utils/index.js
+/**
+ * @module utils
+ * @description
+ * Central barrel file — re-exports every public utility from the `utils/`
+ * directory so consumers can import from a single entry point:
+ *
+ * ```js
+ * import { colors, toREM, addNavigation, TextInputValidator } from './utils';
+ * ```
+ *
+ * Included utilities:
+ * - **themes**         — color palette, theme switching, CSS variable sync
+ * - **getWidgetProps** — read widget `_props` safely
+ * - **syntaxHighlight** — JavaScript/FletBox tokenizer and HTML highlighter
+ * - **markdownParser** — markdown → FletBox widget tree converter
+ * - **visualEffects**  — CSS animations (stripes, shimmer, glow, pulse)
+ * - **stackPosition**  — dataset-based absolute positioning for Stack children
+ * - **units**          — px ↔ rem conversion helpers
+ * - **navigation**     — tree-navigation mixin for widget objects
+ * - **stopWebRefresh** — disables browser refresh gestures
+ * - **TextInputValidator** — input filtering and XSS sanitization
+ * - **mediaTime**      — time formatting for media players
+ */
+export {
+  colors,
+  setTheme,
+  getTheme,
+  toggleTheme,
+  subscribeTheme,
+  applySystemTheme,
+  watchSystemTheme,
+  getColor,
+  palettes,
+  ThemeProvider,
+  useTheme,
+} from "./themes.js";
+export {
+  getWidgetProps,
+  getWidgetProp,
+  stringifyWidgetProps,
+} from "./getWidgetProps.js";
+export {
+  tokenize,
+  generateHighlightedHtml,
+  highlightColors,
+} from "./syntaxHighlight.js";
+export {
+  markdownToWidgets,
+  parseMarkdownToWidgets,
+  parseInlineToWidgets,
+  parseMarkdown,
+  parseInlineMarkdown,
+  escapeHtml,
+} from "./markdownParser.js";
+export {
+  applyStripes,
+  removeStripes,
+  applyShimmer,
+  applyGlow,
+  applyIndeterminate,
+  applyPulse,
+  injectKeyframes,
+} from "./visualEffects.js";
+export { default as stackPosition } from "./stackPosition.js";
+export { toREM, setBaseFontSize, toPX, getBaseFontSize } from "./units.js";
+export { addNavigation } from "./navigation.js";
+export { stopWebRefresh } from "./stopWebRefresh.js";
+export { TextInputValidator } from "./TextInputValidator.js";
+export {
+  formatMediaTime,
+  formatMediaTimeLong,
+  getProgressPercent,
+  percentToSeconds,
+  formatMediaProgress,
+} from "./mediaTime.js";

package/src/utils/markdownParser.js

@@ -0,0 +1,368 @@
+// utils/markdownParser.js
+import { DataTable } from "../widgets/DataTable.js";
+import { Text } from "../widgets/Text.js";
+import { Container } from "../widgets/Container.js";
+import { Row } from "../widgets/Row.js";
+import { Icon } from "../widgets/Icon.js";
+import { CodeViewer } from "../widgets/CodeViewer.js";
+import { colors } from "./themes.js";
+
+// ========== TABLES ==========
+const isTableLine = (line) => {
+  return (
+    line.includes("|") &&
+    line.trim().startsWith("|") &&
+    line.trim().endsWith("|")
+  );
+};
+
+const isTableSeparatorLine = (line) => {
+  return (
+    line.includes("|") &&
+    line.includes("-") &&
+    /[\s\|]*:?-+:?[\s\|]*/.test(line)
+  );
+};
+
+const parseTable = (lines, startIndex) => {
+  let i = startIndex;
+  const headerLine = lines[i].trim();
+  const separatorLine = lines[i + 1]?.trim();
+
+  if (!isTableLine(headerLine)) return null;
+  if (!isTableSeparatorLine(separatorLine)) return null;
+
+  const headers = headerLine
+    .split("|")
+    .filter((cell) => cell.trim() !== "")
+    .map((cell) => cell.trim());
+
+  if (headers.length === 0) return null;
+
+  i += 2;
+
+  const rows = [];
+  while (i < lines.length) {
+    const line = lines[i].trim();
+    if (!isTableLine(line)) break;
+
+    const cells = line
+      .split("|")
+      .filter((cell) => cell.trim() !== "")
+      .map((cell) => cell.trim());
+
+    if (cells.length === headers.length) {
+      const rowData = {};
+      headers.forEach((header, idx) => {
+        rowData[header] = cells[idx] || "";
+      });
+      rows.push(rowData);
+    }
+    i++;
+  }
+
+  const columns = headers.map((h) => ({ key: h, label: h }));
+  const tableWidget = DataTable({
+    columns: columns,
+    rows: rows,
+    striped: true,
+    hoverable: true,
+    bordered: true,
+    compact: false,
+  });
+
+  return { widget: tableWidget, nextIndex: i };
+};
+
+// ========== INLINE TEXT ==========
+/**
+ * Parses an inline markdown string and converts it to an array of widgets.
+ * Currently handles `**bold**` syntax; all other text is rendered as plain
+ * `Text` widgets. Multiple parts are wrapped in a `Row` with word-wrapping.
+ * @param {string} text - Inline markdown text to parse.
+ * @returns {Array} Array of widget instances (Text or Row).
+ */
+export const parseInlineToWidgets = (text) => {
+  if (!text) return [Text({ text: "" })];
+
+  const parts = [];
+  let remaining = text;
+
+  const boldRegex = /\*\*(.*?)\*\*/;
+  let match;
+  while ((match = boldRegex.exec(remaining)) !== null) {
+    const before = remaining.substring(0, match.index);
+    if (before) parts.push(Text({ text: before, size: 14 }));
+    parts.push(Text({ text: match[1], size: 14, weight: "bold" }));
+    remaining = remaining.substring(match.index + match[0].length);
+  }
+  if (remaining) parts.push(Text({ text: remaining, size: 14 }));
+
+  if (parts.length === 0) return [Text({ text: text, size: 14 })];
+  if (parts.length === 1) return parts;
+
+  return [
+    Row({ alignItems: "center", gap: 4, children: parts, flexWrap: "wrap" }),
+  ];
+};
+
+// ========== MAIN PARSER ==========
+/**
+ * Converts a markdown string to an array of FletBox widgets.
+ *
+ * Supported syntax:
+ * - Headings: `#`, `##`, `###`
+ * - Bold: `**text**`
+ * - Horizontal rules: `---` / `***`
+ * - Blockquotes: `> text`
+ * - Unordered lists: `- item`, `* item`, `+ item`
+ * - Ordered lists: `1. item`
+ * - Fenced code blocks: `` ```lang ``
+ * - Tables (GFM pipe tables)
+ * - Empty lines (spacers)
+ * - Plain paragraphs
+ *
+ * @param {string} text - Markdown source string.
+ * @param {Object} [options={}] - Rendering options.
+ * @param {number} [options.codeMaxHeight=300] - Maximum height in pixels for code blocks.
+ * @param {number} [options.codeFontSize=12] - Font size in pixels for code blocks.
+ * @returns {Array} Flat array of widget instances ready to be rendered.
+ */
+export const markdownToWidgets = (text, options = {}) => {
+  if (!text) return [];
+
+  const widgets = [];
+  const lines = text.split("\n");
+  let i = 0;
+  let inCodeBlock = false;
+  let codeContent = [];
+  let codeLang = "";
+
+  while (i < lines.length) {
+    const line = lines[i];
+
+    // CODE BLOCKS
+    if (!inCodeBlock && line.trim().startsWith("```")) {
+      inCodeBlock = true;
+      codeLang = line.trim().replace(/```/g, "").trim();
+      i++;
+      continue;
+    }
+    if (inCodeBlock && line.trim().startsWith("```")) {
+      inCodeBlock = false;
+      const codeWidget = CodeViewer({
+        code: codeContent.join("\n"),
+        language: codeLang || "javascript",
+        maxHeight: options.codeMaxHeight || 300,
+        fontSize: options.codeFontSize || 12,
+        showHeader: false,
+        showLineNumbers: true,
+      });
+      widgets.push(codeWidget);
+      codeContent = [];
+      codeLang = "";
+      i++;
+      continue;
+    }
+    if (inCodeBlock) {
+      codeContent.push(line);
+      i++;
+      continue;
+    }
+
+    // TABLES
+    if (
+      isTableLine(line) &&
+      i + 1 < lines.length &&
+      isTableSeparatorLine(lines[i + 1])
+    ) {
+      const result = parseTable(lines, i);
+      if (result) {
+        widgets.push(result.widget);
+        i = result.nextIndex;
+        continue;
+      }
+    }
+
+    // HEADERS
+    if (line.match(/^### /)) {
+      widgets.push(
+        Text({
+          text: line.substring(4),
+          size: 18,
+          weight: "bold",
+          marginTop: 16,
+          marginBottom: 8,
+        }),
+      );
+      i++;
+      continue;
+    }
+    if (line.match(/^## /)) {
+      widgets.push(
+        Text({
+          text: line.substring(3),
+          size: 22,
+          weight: "bold",
+          marginTop: 20,
+          marginBottom: 10,
+        }),
+      );
+      i++;
+      continue;
+    }
+    if (line.match(/^# /)) {
+      widgets.push(
+        Text({
+          text: line.substring(2),
+          size: 28,
+          weight: "bold",
+          marginTop: 24,
+          marginBottom: 12,
+        }),
+      );
+      i++;
+      continue;
+    }
+
+    // HORIZONTAL RULE
+    if (line.match(/^---$/) || line.match(/^\*\*\*$/)) {
+      widgets.push(
+        Container({ height: 1, bgColor: colors.border, marginVertical: 16 }),
+      );
+      i++;
+      continue;
+    }
+
+    // BLOCKQUOTE
+    if (line.match(/^> /)) {
+      const content = line.substring(2);
+      const innerWidgets = parseInlineToWidgets(content);
+      widgets.push(
+        Container({
+          padding: 12,
+          bgColor: `${colors.primary}10`,
+          borderRadius: 8,
+          borderLeft: `4px solid ${colors.primary}`,
+          marginVertical: 8,
+          child: Row({ alignItems: "center", gap: 8, children: innerWidgets }),
+        }),
+      );
+      i++;
+      continue;
+    }
+
+    // UNORDERED LIST
+    if (line.match(/^\s*[-*+]\s/)) {
+      const content = line.replace(/^\s*[-*+]\s/, "");
+      const innerWidgets = parseInlineToWidgets(content);
+      widgets.push(
+        Row({
+          alignItems: "center",
+          gap: 8,
+          marginVertical: 4,
+          children: [
+            Icon({ name: "circle", size: 8, color: colors.primary }),
+            ...innerWidgets,
+          ],
+        }),
+      );
+      i++;
+      continue;
+    }
+
+    // ORDERED LIST
+    if (line.match(/^\s*\d+\.\s/)) {
+      const number = line.match(/^\s*(\d+)\.\s/)[1];
+      const content = line.replace(/^\s*\d+\.\s/, "");
+      const innerWidgets = parseInlineToWidgets(content);
+      widgets.push(
+        Row({
+          alignItems: "center",
+          gap: 8,
+          marginVertical: 4,
+          children: [
+            Text({
+              text: `${number}.`,
+              size: 14,
+              weight: "bold",
+              color: colors.primary,
+            }),
+            ...innerWidgets,
+          ],
+        }),
+      );
+      i++;
+      continue;
+    }
+
+    // EMPTY LINE
+    if (line.trim() === "") {
+      widgets.push(Container({ height: 8 }));
+      i++;
+      continue;
+    }
+
+    // PARAGRAPH
+    const paragraphWidgets = parseInlineToWidgets(line);
+    if (paragraphWidgets.length === 1) {
+      widgets.push(paragraphWidgets[0]);
+    } else {
+      widgets.push(
+        Row({
+          alignItems: "center",
+          gap: 4,
+          children: paragraphWidgets,
+          flexWrap: "wrap",
+          marginVertical: 4,
+        }),
+      );
+    }
+    i++;
+  }
+
+  return widgets;
+};
+
+// ========== MAIN EXPORTS ==========
+/** Alias for {@link markdownToWidgets}. */
+export const parseMarkdownToWidgets = markdownToWidgets;
+
+/**
+ * Identity function — returns the raw markdown string unchanged.
+ * Provided for API symmetry where a parse step is expected but plain text is acceptable.
+ * @param {string} text - Markdown source.
+ * @returns {string} The same string, unmodified.
+ */
+export const parseMarkdown = (text) => text;
+
+/**
+ * Identity function — returns the raw inline markdown string unchanged.
+ * @param {string} text - Inline markdown source.
+ * @returns {string} The same string, unmodified.
+ */
+export const parseInlineMarkdown = (text) => text;
+
+/**
+ * Escapes HTML special characters to prevent injection when inserting into innerHTML.
+ * Converts `& < > " '` to their corresponding HTML entities.
+ * @param {string} text - Raw text to escape.
+ * @returns {string} HTML-safe string.
+ */
+export const escapeHtml = (text) =>
+  String(text)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+
+// Default export
+export default {
+  markdownToWidgets,
+  parseMarkdownToWidgets,
+  parseInlineToWidgets,
+  parseMarkdown,
+  parseInlineMarkdown,
+  escapeHtml,
+};

package/src/utils/mediaTime.js

@@ -0,0 +1,79 @@
+// src/utils/mediaTime.js
+// Time formatting utilities for media players (audio/video)
+
+/**
+ * Formats a duration in seconds as a `MM:SS` string.
+ * Returns `"00:00"` for falsy or `NaN` values.
+ * @param {number} seconds - Duration in seconds.
+ * @returns {string} Zero-padded `"MM:SS"` string (e.g. `"03:07"`).
+ * @example
+ * formatMediaTime(187)  // "03:07"
+ * formatMediaTime(0)    // "00:00"
+ */
+export const formatMediaTime = (seconds) => {
+  if (!seconds || isNaN(seconds)) return "00:00";
+  const mins = Math.floor(seconds / 60);
+  const secs = Math.floor(seconds % 60);
+  return `${mins.toString().padStart(2, "0")}:${secs.toString().padStart(2, "0")}`;
+};
+
+/**
+ * Formats a duration in seconds as a `HH:MM:SS` or `MM:SS` string,
+ * including hours only when the value is 3600 seconds or more.
+ * Returns `"00:00"` for falsy or `NaN` values.
+ * @param {number} seconds - Duration in seconds.
+ * @returns {string} Zero-padded `"HH:MM:SS"` or `"MM:SS"` string.
+ * @example
+ * formatMediaTimeLong(3723)  // "01:02:03"
+ * formatMediaTimeLong(187)   // "03:07"
+ */
+export const formatMediaTimeLong = (seconds) => {
+  if (!seconds || isNaN(seconds)) return "00:00";
+  const hrs = Math.floor(seconds / 3600);
+  const mins = Math.floor((seconds % 3600) / 60);
+  const secs = Math.floor(seconds % 60);
+  if (hrs > 0) {
+    return `${hrs.toString().padStart(2, "0")}:${mins.toString().padStart(2, "0")}:${secs.toString().padStart(2, "0")}`;
+  }
+  return `${mins.toString().padStart(2, "0")}:${secs.toString().padStart(2, "0")}`;
+};
+
+/**
+ * Calculates the playback progress as a percentage between 0 and 100.
+ * Returns `0` when `total` is falsy or zero to avoid division by zero.
+ * @param {number} current - Current playback position in seconds.
+ * @param {number} total - Total media duration in seconds.
+ * @returns {number} Progress percentage clamped to `[0, 100]`.
+ * @example
+ * getProgressPercent(30, 120)  // 25
+ * getProgressPercent(0, 0)     // 0
+ */
+export const getProgressPercent = (current, total) => {
+  if (!total || total <= 0) return 0;
+  return Math.min(100, Math.max(0, (current / total) * 100));
+};
+
+/**
+ * Converts a progress percentage back to an absolute position in seconds.
+ * Returns `0` when `total` is falsy or zero.
+ * @param {number} percent - Progress value between 0 and 100.
+ * @param {number} total - Total media duration in seconds.
+ * @returns {number} Corresponding position in seconds.
+ * @example
+ * percentToSeconds(25, 120)  // 30
+ */
+export const percentToSeconds = (percent, total) => {
+  if (!total || total <= 0) return 0;
+  return (percent / 100) * total;
+};
+
+/**
+ * Formats the combined current/total progress as a `"MM:SS / MM:SS"` string.
+ * Delegates to {@link formatMediaTime} for each value.
+ * @param {number} current - Current playback position in seconds.
+ * @param {number} total - Total media duration in seconds.
+ * @returns {string} Progress string (e.g. `"01:23 / 04:56"`).
+ */
+export const formatMediaProgress = (current, total) => {
+  return `${formatMediaTime(current)} / ${formatMediaTime(total)}`;
+};