dataface 0.1.2__py3-none-any.whl

dataface/core/render/template_loader.py

@@ -0,0 +1,69 @@
+"""Template loader for SVG/HTML templates.
+
+Stage: RENDER
+Purpose: Load and render Jinja2 templates for SVG and HTML rendering.
+
+This module provides a single function for loading templates from the
+render/templates directory and rendering them with Jinja2.
+
+Note: The global _jinja_env uses lazy initialization without locking.
+This is acceptable for single-threaded use. In multi-threaded contexts
+(e.g., Django), the worst case is redundant Environment creation.
+"""
+
+from pathlib import Path
+from typing import Any
+
+from jinja2 import (
+    ChoiceLoader,
+    DictLoader,
+    Environment,
+    FileSystemLoader,
+    select_autoescape,
+)
+
+# Lazy-initialized Jinja environment (not thread-safe, but acceptable)
+_jinja_env: Environment | None = None
+
+
+def _get_jinja_env() -> Environment:
+    """Get or create Jinja environment for templates."""
+    global _jinja_env
+
+    if _jinja_env is None:
+        template_dir = Path(__file__).parent / "templates"
+        fonts_dir = Path(__file__).parent / "fonts"
+        # Load only the emoji partial from fonts/ via DictLoader — avoids exposing
+        # binaries, license files, and README as includeable Jinja templates.
+        emoji_partial = (fonts_dir / "_emoji_font_face.css").read_text()
+        _jinja_env = Environment(
+            loader=ChoiceLoader(
+                [
+                    FileSystemLoader(str(template_dir)),
+                    DictLoader({"_emoji_font_face.css": emoji_partial}),
+                ]
+            ),
+            autoescape=select_autoescape(["html", "xml", "svg"]),
+        )
+
+    return _jinja_env
+
+
+def render_template(template_path: str, **context: Any) -> str:
+    """Render a template with the given context.
+
+    This is the ONLY function needed for template loading. Use it for:
+    - Templates with variables: render_template("svg/grid_pattern.svg", **ctx)
+    - Static templates: render_template("svg/grid_pattern.svg")
+
+    Args:
+        template_path: Path to template relative to templates/ directory
+                      (e.g., "svg/grid_pattern.svg")
+        **context: Template context variables (optional)
+
+    Returns:
+        Rendered template string
+    """
+    env = _get_jinja_env()
+    template = env.get_template(template_path)
+    return template.render(**context)

dataface/core/render/templates/controls/_styles.css

@@ -0,0 +1,606 @@
+/* ==========================================================================
+   Variable Controls - CSS Styles
+
+   These styles use CSS custom properties (variables) set on the .dft-variables
+   container based on the current theme. This enables:
+   - Centralized theming (colors set once, inherited everywhere)
+   - Hover/focus states (impossible with inline styles)
+   - Easier maintenance (styles in one place)
+
+   CSS Custom Properties (set by renderer based on theme):
+   --dft-font-family: Container font family
+   --dft-label-color: Label text color
+   --dft-label-weight: Label font weight
+   --dft-label-size: Label font size in px
+   --dft-text-color: Input text color
+   --dft-value-color: Value text color (slider, readonly)
+   --dft-value-family: Value font family
+   --dft-value-size: Value font size in px
+   --dft-value-weight: Value font weight
+   --dft-value-numeric-variant: Font variant numeric (tabular-nums/normal)
+   --dft-placeholder-color: Placeholder/hint text color (unselected variable inputs)
+   Note: font-style, text-decoration, and case are cascaded through MergedFontStyle
+   but are not consumed by these controls — the control renderer emits only the
+   properties listed above (family, size, weight, color). Adding style/decoration/case
+   here would require extend the CSS custom-property emit path for control elements.
+   --dft-input-bg: Input background color
+   --dft-input-border: Input border color
+   --dft-accent-color: Accent/focus color
+   --dft-muted-color: Muted/secondary text color
+   --dft-focus-ring: Focus ring color (CSS color-mix, requires Color Level 5)
+   ========================================================================== */
+
+/* --------------------------------------------------------------------------
+   Variables Container
+   -------------------------------------------------------------------------- */
+
+.dft-variables {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 15px;
+  align-items: center;
+  background: #f8f9fa;
+  padding: 10px 15px;
+  border-radius: 6px;
+  font-family: var(--dft-font-family, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif);
+  box-sizing: border-box;
+  height: 100%;
+  /* Allow absolutely-positioned popovers (daterange chip) to overflow the
+     SVG clipping rect when this container is embedded inside an SVG element. */
+  overflow: visible;
+}
+
+/* --------------------------------------------------------------------------
+   Individual Control Wrapper
+   -------------------------------------------------------------------------- */
+
+.dft-variable-control {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+/* --------------------------------------------------------------------------
+   Labels
+   -------------------------------------------------------------------------- */
+
+.dft-variable-label {
+  font-weight: var(--dft-label-weight, 500);
+  color: var(--dft-label-color, #495057);
+  font-size: var(--dft-label-size, inherit);
+  white-space: nowrap;
+  user-select: none;
+}
+
+/* --------------------------------------------------------------------------
+   Base Input Styles (applies to all input types)
+   -------------------------------------------------------------------------- */
+
+.dft-variable-input {
+  padding: 4px 8px;
+  border: 1px solid var(--dft-input-border, #ced4da);
+  border-radius: 4px;
+  background: var(--dft-input-bg, #ffffff);
+  color: var(--dft-text-color, #333333);
+  font-size: inherit;
+  font-family: inherit;
+  transition: border-color 0.15s ease, box-shadow 0.15s ease;
+}
+
+.dft-variable-input:hover {
+  border-color: var(--dft-accent-color, #667eea);
+}
+
+.dft-variable-input:focus {
+  outline: none;
+  border-color: var(--dft-accent-color, #667eea);
+  box-shadow: 0 0 0 3px var(--dft-focus-ring, rgba(102, 126, 234, 0.2));
+}
+
+.dft-variable-input:disabled {
+  opacity: 0.6;
+  cursor: not-allowed;
+}
+
+/* Placeholder / unselected state — server-rendered data-placeholder="true" tags
+   any input whose value is empty/null. Reads lighter than the selected-value
+   text so the strip is scannable at a glance. */
+.dft-variable-input[data-placeholder="true"] {
+  color: var(--dft-placeholder-color, var(--dft-text-color));
+}
+
+/* --------------------------------------------------------------------------
+   Select / Dropdown
+   -------------------------------------------------------------------------- */
+
+select.dft-variable-input {
+  cursor: pointer;
+  min-width: 120px;
+  padding-right: 24px; /* Space for dropdown arrow */
+  appearance: none;
+  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='12' viewBox='0 0 12 12'%3E%3Cpath fill='%23666' d='M2 4l4 4 4-4'/%3E%3C/svg%3E");
+  background-repeat: no-repeat;
+  background-position: right 8px center;
+}
+
+/* --------------------------------------------------------------------------
+   Checkbox
+   -------------------------------------------------------------------------- */
+
+.dft-variable-checkbox {
+  cursor: pointer;
+}
+
+.dft-variable-checkbox input[type="checkbox"] {
+  width: 16px;
+  height: 16px;
+  cursor: pointer;
+  accent-color: var(--dft-accent-color, #667eea);
+  margin: 0;
+}
+
+.dft-variable-checkbox .dft-variable-label {
+  cursor: pointer;
+}
+
+/* --------------------------------------------------------------------------
+   Slider / Range
+   -------------------------------------------------------------------------- */
+
+.dft-variable-slider {
+  gap: 8px;
+}
+
+.dft-variable-slider input[type="range"] {
+  width: 120px;
+  cursor: pointer;
+  accent-color: var(--dft-accent-color, #667eea);
+  height: 4px;
+  border: none;
+  background: transparent;
+}
+
+.dft-variable-slider-value {
+  min-width: 30px;
+  color: var(--dft-value-color, #333333);
+  font-family: var(--dft-value-family, inherit);
+  font-size: var(--dft-value-size, inherit);
+  font-weight: var(--dft-value-weight, inherit);
+  font-variant-numeric: var(--dft-value-numeric-variant, tabular-nums);
+  text-align: right;
+}
+
+/* --------------------------------------------------------------------------
+   Text Input
+   -------------------------------------------------------------------------- */
+
+input[type="text"].dft-variable-input {
+  width: 150px;
+}
+
+/* --------------------------------------------------------------------------
+   Number Input
+   -------------------------------------------------------------------------- */
+
+input[type="number"].dft-variable-input {
+  width: 80px;
+  font-variant-numeric: var(--dft-value-numeric-variant, tabular-nums);
+}
+
+/* Remove spinner buttons for cleaner look */
+input[type="number"].dft-variable-input::-webkit-inner-spin-button,
+input[type="number"].dft-variable-input::-webkit-outer-spin-button {
+  -webkit-appearance: none;
+  margin: 0;
+}
+
+input[type="number"].dft-variable-input {
+  -moz-appearance: textfield;
+}
+
+/* --------------------------------------------------------------------------
+   Date Input
+   -------------------------------------------------------------------------- */
+
+input[type="date"].dft-variable-input {
+  cursor: pointer;
+}
+
+/* --------------------------------------------------------------------------
+   Date Range — chip trigger + popover
+   -------------------------------------------------------------------------- */
+
+/* Derived accent values are inlined at each consumer (range tint, focus ring,
+   primary-hover) rather than defined as :root-level custom properties.
+   Why: when a custom property's value contains a var() reference, the inner
+   var() resolves at the DEFINING element, not the consumer. --dft-accent-color
+   is set on .dft-variables (inline by the renderer) and snapshotted onto the
+   reparented popover — not on :root. So a :root-level
+   `--dft-accent-hover: color-mix(in srgb, var(--dft-accent-color, #667eea) 85%, black)`
+   computes once at :root where --dft-accent-color is unset, freezing the
+   fallback indigo into the value the popover then inherits. Inlining the
+   color-mix at the rule that uses it forces the substitution to happen at the
+   consumer, where --dft-accent-color carries the theme's accent. */
+
+/* Positioning anchor for the popover. */
+.dft-chip-host {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+}
+
+/* Chip trigger button — transparent background blends with the canvas;
+   the border carries the "this is a control" signal. */
+.dft-chip {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  /* Padding matches the variables-bar select controls (theme.variables.input.padding)
+     so the chip's height aligns with Plan/Country selects sitting next to it.
+     The prototype used 6/10, but the chip there stood alone — in DFT the chip
+     shares a strip with `select.dft-variable-input` (4/8 padding), and the
+     tallness mismatch reads as inconsistency. */
+  padding: 4px 8px;
+  border: 1px solid var(--dft-input-border, #ced4da);
+  border-radius: 4px;
+  background: transparent;
+  cursor: pointer;
+  font-family: inherit;
+  /* Inherit from the .dft-variables flex container (11px in theme YAML) so
+     the chip text baseline matches the adjacent select.dft-variable-input
+     controls. A hardcoded 13px here lifts the chip ~1.8px above its
+     neighbours and breaks the title-inline header alignment.
+     NOTE: never write a literal angle-bracket tag like the s-e-l-e-c-t one
+     inside a comment in this file. The CSS gets injected verbatim into the
+     rendered SVG inside a style element, and the SVG XML parser tokenises
+     such occurrences as tag openers, breaking PNG conversion. */
+  font-size: inherit;
+  font-variant-numeric: tabular-nums;
+  color: var(--dft-text-color, #333333);
+  /* Fade border-color and focus ring together to avoid asymmetric snap. */
+  transition: border-color 80ms, box-shadow 80ms;
+}
+
+/* Border-only hover — no background tint (quieter across the variable bar). */
+.dft-chip:hover {
+  border-color: var(--dft-muted-color, #6c757d);
+}
+
+.dft-chip:focus {
+  outline: none;
+  border-color: var(--dft-accent-color, #667eea);
+  box-shadow: 0 0 0 3px color-mix(in srgb, var(--dft-accent-color, #667eea) 18%, transparent);
+}
+
+/* Chip icon — always full ink; placeholder dims text only, not the icon. */
+.dft-chip-icon {
+  display: inline-flex;
+  align-items: center;
+  flex-shrink: 0;
+  width: 16px;
+  height: 16px;
+  color: var(--dft-text-color, #333333);
+}
+
+.dft-chip-icon svg {
+  width: 100%;
+  height: 100%;
+}
+
+.dft-chip-label {
+  font-weight: 500;
+  white-space: nowrap;
+}
+
+/* Placeholder state — lighter text, normal weight. */
+.dft-chip[data-placeholder="true"] .dft-chip-label {
+  color: var(--dft-placeholder-color, var(--dft-muted-color, #6c757d));
+  font-weight: 400;
+}
+
+/* Clear button — sibling of .dft-chip inside .dft-chip-host.
+   Hidden until the chip carries data-active; shown via adjacent-sibling selector. */
+.dft-chip-clear {
+  display: none;
+  width: 16px;
+  height: 16px;
+  line-height: 14px;
+  text-align: center;
+  border-radius: 50%;
+  color: var(--dft-muted-color, #6c757d);
+  font-size: 14px;
+  cursor: pointer;
+  background: none;
+  border: none;
+  padding: 0;
+}
+
+.dft-chip-clear:hover {
+  background: var(--dft-input-bg, #ffffff);
+  color: var(--dft-text-color, #333333);
+}
+
+/* Show clear button when the sibling chip carries data-active. */
+.dft-chip[data-active] + .dft-chip-clear {
+  display: inline-block;
+}
+
+/* Popover — hidden by default; .dft-popover-open shows it.
+   The calendar is chrome (same category as a native select dropdown), not
+   editorial content — hardcode Inter/sans so it stays consistent across themes
+   regardless of the page's heading typeface, and survives being reparented to
+   document.body for SVG-stacking escape (where it'd otherwise inherit the
+   body's serif).
+
+   Background uses a dedicated --dft-popover-bg token rather than --dft-input-bg:
+   the variables-bar input background is intentionally `transparent` in the
+   `stark` cascade root so it inherits the page canvas. A popover needs an
+   OPAQUE card surface — falling back to #ffffff matches the prototype's --card.
+
+   NOTE: avoid angle brackets in any comment inside this stylesheet. resvg's
+   CSS parser used by the PNG and PDF converters mis-reads them as SVG tag
+   opens (since this whole CSS is embedded in an SVG style element), then
+   errors at the closing style tag — silently breaking every dashboard
+   download. The first version of this comment shipped with "select" between
+   angle brackets and broke the test_dashboard_download_supported_format
+   tests. */
+.dft-popover {
+  display: none;
+  position: absolute;
+  top: calc(100% + 6px);
+  left: 0;
+  background: var(--dft-popover-bg, #ffffff);
+  border: 1px solid var(--dft-input-border, #ced4da);
+  border-radius: 8px;
+  box-shadow: 0 6px 20px rgba(0, 0, 0, 0.10);
+  overflow: hidden;
+  z-index: 100;
+  font-family: 'Inter Variable', Inter, system-ui, -apple-system, sans-serif;
+}
+
+.dft-popover.dft-popover-open {
+  display: flex;
+}
+
+/* Preset rail — left column of the popover. Background tracks the theme's
+   subtle-surface step (--dft-popover-rail-bg, emitted by the renderer per
+   theme): gray-50 on white-canvas themes, cream-toned on warm-canvas themes.
+   Distinct from the popover card itself, which is always white-equivalent. */
+.dft-preset-rail {
+  width: 164px;
+  border-right: 1px solid var(--dft-input-border, #ced4da);
+  padding: 10px 0;
+  flex-shrink: 0;
+  background: var(--dft-popover-rail-bg, #fafafa);
+}
+
+.dft-preset-rail button {
+  display: block;
+  width: 100%;
+  padding: 7px 16px;
+  text-align: left;
+  background: none;
+  border: none;
+  cursor: pointer;
+  font-family: inherit;
+  font-size: 13px;
+  color: var(--dft-text-color, #333333);
+}
+
+.dft-preset-rail button:hover {
+  background: var(--dft-input-border, #ced4da);
+}
+
+.dft-preset-rail button.dft-preset-active {
+  background: var(--dft-accent-color, #667eea);
+  color: white;
+}
+
+.dft-preset-divider {
+  height: 1px;
+  background: var(--dft-input-border, #ced4da);
+  margin: 6px 12px;
+}
+
+/* Calendar area — right column, contains header, grid, footer.
+   Explicit width (not flex: 1) so the popover sizes correctly when reparented
+   to document.body for SVG-stacking escape — `position: fixed` parents have
+   no width constraint, and `flex: 1` would stretch to viewport width. */
+.dft-calendar-area {
+  padding: 14px;
+  flex-shrink: 0;
+  width: 272px;
+}
+
+/* All-sans calendar header (the calendar is UI chrome, not editorial content). */
+.dft-cal-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: 10px;
+  padding: 0 4px;
+}
+
+.dft-cal-nav {
+  background: none;
+  border: none;
+  cursor: pointer;
+  font-size: 18px;
+  color: var(--dft-text-color, #333333);
+  padding: 2px 8px;
+  border-radius: 3px;
+}
+
+.dft-cal-nav:hover {
+  background: var(--dft-input-border, #ced4da);
+}
+
+/* min-width keeps nav arrows stable as month name length varies
+   ("May 2026" → "September 2026"). */
+.dft-cal-month {
+  font-weight: 500;
+  font-size: 14px;
+  min-width: 130px;
+  text-align: center;
+  color: var(--dft-text-color, #333333);
+}
+
+/* Fixed-width 7-column grid — 34px per cell. Fixed height eliminates
+   height jumps as the user pages between months (fixedHeight = 42 cells). */
+.dft-cal-grid {
+  display: grid;
+  grid-template-columns: repeat(7, 34px);
+  gap: 0;
+}
+
+.dft-cal-dow {
+  font-size: 11px;
+  color: var(--dft-muted-color, #6c757d);
+  text-align: center;
+  padding: 6px 0 4px;
+  font-weight: 500;
+}
+
+/* Cells — proportional figures (grid is fixed-width, no jitter to prevent).
+   Two visual tiers: in-month (full ink) and out-of-month (muted). */
+.dft-cal-cell {
+  text-align: center;
+  padding: 7px 0;
+  font-family: inherit;
+  font-size: 13px;
+  cursor: pointer;
+  border-radius: 3px;
+  background: none;
+  border: none;
+  color: var(--dft-text-color, #333333);
+  min-height: 18px;
+}
+
+.dft-cal-cell.dft-other-month {
+  color: var(--dft-placeholder-color, var(--dft-muted-color, #6c757d));
+}
+
+.dft-cal-cell:hover {
+  background: var(--dft-input-border, #ced4da);
+}
+
+/* Range tint — accent at 28% over the popover card. */
+.dft-cal-cell.dft-in-range,
+.dft-cal-cell.dft-preview-in-range {
+  background: color-mix(in srgb, var(--dft-accent-color, #667eea) 28%, transparent);
+  color: var(--dft-text-color, #333333);
+}
+
+/* Selected endpoints — solid accent fill. */
+.dft-cal-cell.dft-selected {
+  background: var(--dft-accent-color, #667eea);
+  color: white;
+  font-weight: 500;
+}
+
+/* Hover preview of the second endpoint — outlined, not filled. */
+.dft-cal-cell.dft-preview-end {
+  background: transparent;
+  color: var(--dft-accent-color, #667eea);
+  font-weight: 500;
+  box-shadow: inset 0 0 0 1px var(--dft-accent-color, #667eea);
+}
+
+/* Radius shaping for range endpoints. */
+.dft-cal-cell.dft-selected.dft-range-start { border-radius: 3px 0 0 3px; }
+.dft-cal-cell.dft-selected.dft-range-end   { border-radius: 0 3px 3px 0; }
+.dft-cal-cell.dft-selected.dft-range-start.dft-range-end { border-radius: 3px; }
+
+/* Today marker: weight-only (same ink, heavier weight).
+   Color or ring conflicted with selection visuals. Bold weight is the
+   cleanest "this is today" signal — same hue, different emphasis. */
+.dft-cal-cell.dft-today:not(.dft-selected):not(.dft-preview-end) {
+  font-weight: 700;
+}
+
+/* Footer: only shows when a selection exists; contains the Clear action. */
+.dft-cal-footer {
+  display: flex;
+  gap: 8px;
+  margin-top: 14px;
+  padding-top: 12px;
+  border-top: 1px solid var(--dft-input-border, #ced4da);
+  align-items: center;
+  justify-content: flex-end;
+}
+
+.dft-cal-action {
+  padding: 6px 12px;
+  background: none;
+  border: 1px solid var(--dft-input-border, #ced4da);
+  border-radius: 4px;
+  font-family: inherit;
+  font-size: 12px;
+  cursor: pointer;
+  color: var(--dft-text-color, #333333);
+}
+
+.dft-cal-action:hover {
+  border-color: var(--dft-muted-color, #6c757d);
+}
+
+/* Apply — the explicit-close primary action (lingering popover pattern:
+   commit happens automatically on the second pick, popover stays open
+   until Apply, Apply closes without mutating state). Accent fill, white
+   ink. Hover darkens the accent by mixing 15% black. */
+.dft-cal-action-primary {
+  background: var(--dft-accent-color, #667eea);
+  color: white;
+  border-color: var(--dft-accent-color, #667eea);
+}
+
+.dft-cal-action-primary:hover {
+  background: color-mix(in srgb, var(--dft-accent-color, #667eea) 85%, black);
+  border-color: color-mix(in srgb, var(--dft-accent-color, #667eea) 85%, black);
+}
+
+/* (Clear-pushed-left positioning is set inline in variables.js — see the
+   comment in rebuildCalendar's footer block. Attribute selectors and the
+   :not() pseudo both trip resvg's CSS parser used in the PNG/PDF converter,
+   so this stylesheet sticks to selectors resvg handles cleanly.) */
+
+/* --------------------------------------------------------------------------
+   Readonly / Fallback
+   -------------------------------------------------------------------------- */
+
+.dft-variable-readonly {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.dft-variable-readonly-value {
+  color: var(--dft-value-color, #333333);
+  font-family: var(--dft-value-family, inherit);
+  font-size: var(--dft-value-size, inherit);
+  font-weight: var(--dft-value-weight, inherit);
+}
+
+/* --------------------------------------------------------------------------
+   Loading State
+   -------------------------------------------------------------------------- */
+
+.dft-variable-control.loading {
+  opacity: 0.6;
+  pointer-events: none;
+}
+
+.dft-variable-control.loading::after {
+  content: "";
+  width: 14px;
+  height: 14px;
+  border: 2px solid var(--dft-input-border, #ced4da);
+  border-top-color: var(--dft-accent-color, #667eea);
+  border-radius: 50%;
+  animation: dft-control-spin 0.6s linear infinite;
+}
+
+@keyframes dft-control-spin {
+  to { transform: rotate(360deg); }
+}

dataface/core/render/templates/controls/checkbox.html

@@ -0,0 +1,16 @@
+{# Checkbox Control #}
+<div class="dft-variable-control dft-variable dft-variable-checkbox"
+     data-variable-id="{{ name }}"
+     data-variable-label="{{ label }}"
+     {% if depends_on %}data-depends-on="{{ depends_on | tojson }}"{% endif %}>
+
+  <input type="checkbox"
+         id="var-{{ name }}"
+         name="{{ name }}"
+         class="dft-variable-input"
+         data-variable="{{ name }}"
+         onchange="updateVariable('{{ name | js_escape }}', this.checked)"
+         {% if value %}checked{% endif %}>
+
+  <label class="dft-variable-label" for="var-{{ name }}">{{ label }}</label>
+</div>

dataface/core/render/templates/controls/date.html

@@ -0,0 +1,16 @@
+{# Date Input Control #}
+<div class="dft-variable-control dft-variable"
+     data-variable-id="{{ name }}"
+     data-variable-label="{{ label }}"
+     {% if depends_on %}data-depends-on="{{ depends_on | tojson }}"{% endif %}>
+
+  <label class="dft-variable-label" for="var-{{ name }}">{{ label }}:</label>
+
+  <input type="date"
+         id="var-{{ name }}"
+         name="{{ name }}"
+         class="dft-variable-input"
+         data-variable="{{ name }}"
+         value="{{ value or '' }}"
+         onchange="updateVariable('{{ name | js_escape }}', this.value)">
+</div>