dataface 0.1.2__py3-none-any.whl

dataface/core/defaults/themes/_base.yaml

@@ -0,0 +1,786 @@
+# Internal base theme: _base
+# Internal-only root for the built-in theme cascade. Defines all structural
+# defaults (layout, spacing, sizing, chart geometry) but intentionally omits
+# font families and color values — those are supplied by each named theme.
+# Not meant for direct use; extend this via a named theme that fills in
+# font and color.
+
+style:
+  # Palette role assignments.
+  # Open dict: role → palette file name. Resolver resolves role.alias tokens.
+  palettes:
+    chrome: dft-grays
+    negative: negative
+    positive: positive
+    warning: warning
+    category: category-10
+    category_dark: category-10-dark
+    category_light: category-10-light
+    sequence: dft-seq-blue
+    diverge: dft-div-blue-red
+
+  # Top-level theme role shortcuts. Bare alias → role.alias.
+  roles:
+    ink: chrome.heading
+
+  # Format aliases — d3 specs resolved by name at render time.
+  formats:
+    currency:         "$,.2f"
+    currency_whole:   "$,.0f"
+    currency_compact: "$~s"
+    percent:          ".1%"
+    percent_whole:    ".0%"
+    percent_delta:    "+.1%"
+    compact:          "~s"
+    integer:          ",.0f"
+    number:           ",.2f"
+    date_short:       "%-d %b %Y"
+
+  opacity: 1.0
+
+  board:
+    width: 1200.0
+    default_height: 600.0
+    min_height: 0.0
+    margin: 24.0
+    card_padding: 16.0
+    card_gap: 8.0
+
+  font:
+    # Body floor 11px. Anchored — referenced by style.text.font.size,
+    # style.title.subtitle.font.size, style.variables.font.size below.
+    size:   &size_body 11
+    weight: '400'
+    style: normal
+    decoration: none
+    case: none
+    emoji: monochrome
+
+  border:
+    width: 0.0
+    radius: 0.0
+
+  title:
+    position:
+      anchor: start
+      offset: 10
+    overflow: truncate
+    # Compute heading level from count of titled ancestors (not structural depth).
+    # Set to an integer to lock all face titles to a specific H-level (useful for
+    # embedded dashboards where H1/H2 are reserved by the outer page).
+    level: auto
+    font:
+      size: 18
+      weight: 500
+      case: title
+    # Tight headline leading. Convention: larger type wants tighter line-height
+    # (Bringhurst, Butterick). At ~24px the body 1.5 multiplier reads too airy
+    # between wrapped lines; 1.1 sits in the standard 1.05-1.15 display range.
+    line_height: 1.1
+    # H1–H6 font-size ramp, indexed by face.level - 1.
+    # Paired with width_offsets below — chart_title_spec computes
+    # effective_level = clamp(face.level + 1 + width_offset, 1, 6)
+    # then returns sizes[effective_level - 1].
+    sizes:
+      - 24
+      - 18
+      - 14
+      - 14
+      - 11
+      - 11
+    # Additive level offsets by card pixel width. Added to the base heading
+    # level before indexing the sizes ramp. Tier boundaries (<360, <560, <1100,
+    # ≥1100) live in typography.py as engine constants.
+    # Face headers (level=1) are intentionally larger than chart titles (level=2)
+    # at medium/wide — H1 > H2 is semantically correct for a hierarchy of headings.
+    width_offsets:
+      tiny: 3
+      narrow: 1
+      medium: 0
+      wide: 0
+    min_height: 24.0
+    subtitle:
+      font:
+        size:   *size_body
+        weight: 400
+        case: sentence
+
+  charts:
+    aspect_ratio: 1.5
+    min_height: 150.0
+    max_height: 400.0
+    padding:
+      left: 0.0
+      right: 0.0
+      top: 0.0
+      bottom: 0.0
+    animation_duration: 500.0
+    border:
+      width: 0.0
+      color: transparent
+      radius: 0.0
+
+    axis:
+      domain:
+        visible: false
+        width: 1
+      ticks:
+        visible: false
+        size: 6  # default tick size cascades to all axes; matches VL's geometric idiom
+      grid:
+        visible: true
+        opacity: 1
+        width: 1.5
+        zero:
+          width: 2
+      label:
+        font:
+          size:  &size_label 11
+        padding: 6
+        overlap: "smart"     # VL adaptive default: per-scale dispatch (omits labelOverlap from spec)
+        separation: 16       # 16px minimum gap between adjacent labels
+        # bound, flush, offset, line_height, anchor intentionally absent — VL per-axis defaults apply.
+      title:
+        font:
+          size: 0
+          weight: &weight_bold 600
+          case: title
+        padding: 10
+      # fill is semantically only active on axis_x (ordinal bucketed-time);
+      # required on all AxisStyle instances since the model enforces it.
+      fill: "null"
+
+    axis_x:
+      # Only intentional differences from `axis` — everything else cascades.
+      grid:
+        width: 1      # lighter weight than horizontal grid (axis.grid.width=1.5)
+      ticks:
+        visible: true
+        width: 1
+      label:
+        # Fit-based tilt ladder for overlap=smart on discrete x-axes.
+        # Descending; picker chooses the first angle whose labels fit. Falls
+        # through to -90 + overlap="parity" when no angle fits.
+        tilt_increments: [0, -30, -45, -60, -90]
+      title:
+        font:
+          size: 0  # x-axis title hidden by default; charts opt back in via style.axis_x.title
+      scale:
+        padding: 0  # band/point padding around categorical x-axis values
+      offset: 1
+      # Engine fills missing time buckets on ordinal bucketed-time x-axes.
+      # Bar/line/area inherit this global default. Scatter pins null under
+      # style.charts.scatter.axis_x (layer 3.5) — scatter should never zero-fill or interpolate.
+      fill: "null"
+
+    axis_y:
+      # Y-specific tweaks only — orientation and tick width. Empty
+      # grid/domain/label/title cascade from the canonical `axis`
+      # block via `_fill_axis` at render time, so face-level patches on
+      # `style.axis.*` reach axis_y through the same path.
+      # "auto" → "right" by default; flips to "left" when endpoint labels are
+      # on the right edge (line charts with style.line.endpoint_labels.visible).
+      orient: auto
+      categorical_orient: left
+      ticks:
+        width: 1.5
+      fill: "null"
+
+    axis_quantitative:
+      # Quantitative-specific tweaks only — tabular font on numeric labels and
+      # tick width matching axis_y. Colors cascade from `axis` via `_fill_axis`.
+      ticks:
+        width: 1.5
+      label:
+        font: {}
+      fill: "null"
+      # Default compact SI format for quantitative axes (6M, 1.5B, etc).
+      # Authors override per-chart via chart.format or style.axis_y.format.
+      format: "~s"
+
+    tooltip:
+      format: ",.2f"
+
+    legend:
+      orient: right
+      direction: vertical
+      label:
+        font:
+          size:  *size_label
+        padding: 0.0
+      title:
+        font:
+          size: 12
+          weight: *weight_bold
+          case: title
+        padding: 0.0
+      interactive_legend: true
+
+    view:
+      continuous_width: 360
+      continuous_height: 300
+      discrete_width: 360
+      discrete_height: 360
+      # No bounding box around the plot area by default. Themes can opt back
+      # in by setting stroke to a colour token.
+      stroke: null
+
+    autosize:
+      type: fit
+      contains: padding
+      resize: true
+
+    table:
+      outer_padding: 0.0
+      bottom_padding: 0.0
+      pagination:
+        enabled: true
+        page_size: 20
+      text_baseline_offset: 4.0
+      title_baseline_offset: 16.0
+      title_subtitle_gap: 14.0
+      subtitle:
+        font:
+          size: 15
+      border:
+        width: 1.0
+        radius: 4.0
+      column_layout:
+        default_width: 100.0
+        cell_padding: 8.0
+        width_similarity_threshold: 0.8
+      title_row:
+        height: 40.0
+      more_rows:
+        font:
+          size: 11.0
+      paginator:
+        # Right-aligned chevrons + page numbers below the table. Colours come
+        # from the scaffold gray ramp so the control reads as foreground text
+        # rather than as a divider.
+        font:
+          size: 11.0
+        weight_active: 600
+        weight_inactive: 400
+        weight_chevron: 800  # heavier than the active page so chevrons read as affordances
+        item_width: 18.0  # per-item slot width (hit-rect is narrower; see render code)
+      empty_state:
+        font:
+          size: 14.0
+      spark:
+        padding:
+          top: 4.0
+          right: 2.0
+          bottom: 4.0
+          left: 2.0
+        empty:
+          inset_x: 4.0
+          stroke:
+            width: 1.0
+            dasharray: '4 2'
+        single_value:
+          inset_x: 4.0
+          marker_radius: 2.5
+        columns:
+          gap: 1.0
+          padding: 2.0
+          min_bar_height: 1.0
+          border:
+            width: 0.0
+            color: transparent
+            radius: 1.0
+        bar:
+          default_max: 100.0
+          border:
+            width: 0.0
+            color: transparent
+            radius: 0.0
+          label:
+            inset_x: 4.0
+            # Halo knockout: tracks theme canvas so the label backdrop reads
+            # against any theme background.
+            fill: theme.background
+            fill_opacity: 0.9
+            min_size: 9.0
+            height_offset: 5.0
+        area:
+          fill_opacity: 0.3
+      # Universal default: header rule only. No header fill, no row
+      # striping — those compete with cell-background value encoding
+      # (heatmap fills, threshold alerts). The rule is the single
+      # separator between header and body. Summary/total rules remain
+      # on via row typing.
+      header:
+        # UX-default: header row shown. Authors flip to false for series-keyed
+        # tables (e.g. donut-attached) where the column meanings are obvious
+        # from context.
+        visible: true
+        height: 28.0
+        overflow: wrap-two
+        rule:
+          width: 1
+          continuous: true
+        font:
+          # Semibold column headers. Setting weight in theme YAML keeps the
+          # cascade authoritative so themes can tune without touching the
+          # render layer.
+          weight: '600'
+          case: title
+      wrap: true
+      symbol_mode: anchors
+      row:
+        height: 24.0
+        rule:
+          width: 0.0
+          continuous: false
+        roles:
+          summary:
+            rule_width: 1.0
+          total:
+            rule_width: 0.0
+
+    palette: category-10
+
+    # Global mark defaults — tier-1 of the three-tier mark cascade.
+    # Family-specific overrides live under style.charts.<family>.marks.*
+    # Face-local overrides live under face.style.marks.* (tier-3).
+    marks:
+      bar:
+        border:
+          width: 1
+          # Halo knockout: tracks the theme's canvas so adjacent bars separate
+          # cleanly on any theme background. Resolved at theme-compile time
+          # (see ``_resolve_self_tokens`` in models/style/resolved.py).
+          color: theme.background
+          radius: 2
+        # Bar width is set at the mark layer (band_width = 0.8 → 80% of band
+        # step) so it works on both ordinal and temporal x-scales. The band
+        # scale gutter (padding) stays at 0 so the two layers don't compound.
+        padding: 0
+        band_width: 0.8
+        size: 20.0
+      line:
+        stroke:
+          width: 3.0
+          cap: "round"
+          join: "round"
+        curve: "linear"
+        halo_multiplier: 2.0
+      area:
+        # Soft tinted fill on a cream-knockout undercoat (when multi-series).
+        # The stroke is the colored top edge; values overlap rather than stack
+        # so each series reads as its own silhouette.
+        opacity: 0.16
+        stroke:
+          width: 3.0
+        # Halo: background-color stroke drawn behind the area's top-edge line.
+        halo_multiplier: 2.0
+      point:
+        size: 0
+        opacity: 1
+        filled: true
+        fill: theme.background
+      slice:
+        # gap 0 lets the stroke (canvas-color knockout) be the only
+        # visible separator between slices.
+        gap: 0
+        corner_radius: 3
+        # Canvas-coupling: ``theme.background`` is a self-reference token
+        # resolved at theme-compile time (see ``_resolve_self_tokens`` in
+        # models/style/resolved.py).
+        stroke:
+          color: theme.background
+          width: 3
+          # Round the inner-vertex spike on pies (acute miter at center where
+          # many radial edges converge).
+          join: "round"
+        # Per-slice labels opt in via ``chart.labels: { template, where? }``.
+        labels:
+          offset: 6
+          block_height: 28
+          line_height: 14
+          font:
+            size: 14
+            weight: '500'
+      text:
+        font:
+          size:   *size_label
+        align: center
+      rule:
+        stroke:
+          width: 1
+      rect:
+        stroke: null
+      circle:
+        opacity: 1
+      square:
+        opacity: 1
+      tick:
+        stroke:
+          width: 2
+      trail:
+        stroke:
+          width: 2
+      geoshape:
+        # Halo knockout between regions — tracks theme canvas so the borders
+        # disappear into the page on any theme.
+        stroke:
+          color: theme.background
+          width: 0.5
+      image:
+        aspect: true
+      boxplot:
+        extent: min-max
+      errorbar:
+        ticks: true
+      errorband:
+        opacity: 0.3
+
+    bar:
+      endpoint_labels:
+        visible: false
+        label_offset: 6.0
+      axis_x:
+        grid:
+          visible: false
+        ticks:
+          visible: false
+        label:
+          padding: 6.0
+
+    line:
+      endpoint_labels:
+        visible: false
+        label_offset: 6.0
+
+    area:
+      # Authors who want a stacked area chart opt in via ``chart.stack: "zero"``.
+      stack: false
+      endpoint_labels:
+        visible: false
+        label_offset: 6.0
+      axis_y:
+        ticks:
+          visible: true
+
+    histogram:
+      bin_maxbins: 20
+      # Histogram bars have no visible border (override the global marks.bar.border).
+      marks:
+        bar:
+          border:
+            width: 0.0
+            color: transparent
+            radius: 2.0
+
+    kpi:
+      # KPI uses the tabular sans by default — digits aligned across cards
+      # in a row matter more than text-prose readability for a value card.
+      # The editorial parent theme overrides `kpi.value.font.family` to a
+      # serif value while keeping support/affixes on the tabular sans
+      # (see `themes/editorial.yaml`).
+      # Weight 500 (heading-tier) for the whole card text — the per-tier
+      # hierarchy is carried by size + color, not weight. This cascades
+      # into every slot (value, label, affix, glyph) unless overridden.
+      font:
+        size: 11
+        weight: 500
+      value:
+        font:
+          size: 24
+      label:
+        font:
+          size: 11
+          case: title
+      affix:
+        font:
+          size: 11
+      glyph:
+        # Indicator glyphs (▲▼●) sit next to the value as markers, not
+        # second headlines — drawn at body/narrow tier so a triangle's
+        # visual mass doesn't compete with the digits.
+        font:
+          size: 11
+      min_card_width: 100.0
+      default_width: 300.0
+      default_height: 48.0
+      # Inner inset. Vertical 4 keeps the three text slots (label / value /
+      # support) close enough to read as one unit in the dense default KPI
+      # card height (48px). Horizontal 0 lets KPI text sit flush with the
+      # card content origin, so it aligns with page headers, text blocks,
+      # and chart content above/below — all of which render at the same
+      # card_padding offset applied by the layout wrapper.
+      # Trade-off: KPI text no longer aligns with a sibling table's first
+      # cell content (table.columns.cell_padding 8). Override left/right
+      # back to 8.0 in a derived theme if KPI↔table row alignment matters
+      # more than KPI↔header alignment for that brand.
+      content_padding:
+        top: 4.0
+        right: 0.0
+        bottom: 4.0
+        left: 0.0
+      border:
+        width: 0.0
+        color: transparent
+        radius: 0.0
+      # Semantic tone palette for KPI value/glyph and support rows.
+      # Three tones only: positive, negative, warning. Tokens resolved via
+      # palette role dispatch (positive.solid → palettes.positive → positive.yml).
+      tones:
+        positive: positive.solid
+        negative: negative.solid
+        warning: warning.solid
+
+    spark_bar:
+      bar:
+        height: 18.0
+        padding: 2.0
+      label:
+        visible: true
+        width: 80.0
+      count:
+        visible: true
+        width: 50.0
+      max_bars: 10
+      font:
+        size: 11.0
+      subtitle:
+        font:
+          size: 10
+      border:
+        width: 0.0
+        color: transparent
+        radius: 2.0
+
+    # Attached chart.data_table primitive (spec §4, ADR-002).
+    # Universal tier-1 defaults. Per-chart-type tier-2 lives nested under
+    # bar/line/area as data_table: {...}.
+    data_table:
+      font:
+        size: 11
+      # No divider rule by default — strip flows directly from the x-axis.
+      # Themes that want a visible separator can set width > 0 and color.
+      divider:
+        width: 0
+        continuous: true
+      row:
+        padding:
+          vertical: 2.0
+          horizontal: 6.0
+        rule:
+          width: 0.0
+          continuous: true
+      label:
+        font:
+          weight: '500'
+          case: title
+      number_align: right
+      padding_top: 8
+      padding_bottom: 4
+      # Always reserve 2 axis-label lines above the strip so yearly boundary
+      # ticks (e.g. ['Jan', '2024']) don't overlap the strip top edge.  Themes
+      # that use a year-only label cadence (single line always) can set 1.
+      label_max_lines: 2
+      # Pre-launch intentional flip: "top" is the universal default.
+      # Faces that require below-plot layout set position: bottom explicitly.
+      position: top
+
+    # build_patch_model_ext-based types: TYPE_CHECKING stub shows required fields from
+    # _ChartStyleBase, so mypy can't verify zero-arg construction. These stay required.
+    scatter:
+      # Scatter always breaks at missing buckets (honest dots). Pinned here so a
+      # future change to style.charts.axis_x.fill does not connect gaps on point marks.
+      # Bar is intentionally NOT pinned: an author who opts into fill: linear on a bar
+      # chart is accepting that synthesized bars look identical to real query rows.
+      # Line/area inherit the global default and are the primary use case for linear/curve.
+      axis_x:
+        fill: "null"
+      marks:
+        point:
+          # Global marks.point.size is 0 (hides line-chart point overlays). Scatter
+          # needs visible dots — 60 sq px ≈ 4.4px radius, a clean unobtrusive dot.
+          size: 60
+
+    pie:
+      aspect_ratio: 1.0
+      # Donut center total — the big number on top, smaller caption below.
+      # Authors opt in via ``chart.total: { label, format }``; this slot
+      # only contributes typography.
+      total:
+        value:
+          font:
+            size: 18
+            weight: '600'
+        label:
+          font:
+            size: 11
+
+    # Choropleth (color-encoded) map — renamed from 'map' in ADR-015.
+    # geo_source is a chart-root channel (chart.geo_source), not a style field.
+    geoshape:
+      aspect_ratio: 1.2
+      projection:
+        type: albersUsa
+      color_scheme: blues
+
+    # Point map (scatter over geography) — renamed from 'geoshape' in ADR-015.
+    point_map:
+      aspect_ratio: 1.2
+      projection:
+        type: mercator
+
+    heatmap:
+      cell_padding: 2.0
+      color_scheme: blues
+
+    # See scatter comment above for why these three stay as {}.
+    boxplot: {}
+    errorbar: {}
+    errorband: {}
+
+    # Series-label primitive. Typography for any text mark that names a
+    # data series — endpoint labels, direct stack labels,
+    # slice callouts. Placement is family-specific; typography is shared.
+    # font.family + font.weight cascade from charts.font; font.color is
+    # filled per-series by the renderer's dark-companion palette pairing.
+    series_label:
+      font:
+        size: 14
+
+    callout:
+      background: negative.bg
+      padding: 12.0
+      section_gap: 10.0
+      border:
+        width: 1.0
+        color: negative.border
+        radius: 4.0
+      title:
+        font:
+          color: negative.solid
+          size: 13.0
+          weight: bold
+          case: title
+        y_offset: 0.0
+      message:
+        font:
+          color: negative.text
+          size: 11.0
+        y_offset: 0.0
+
+
+  text:
+    font:
+      size:   *size_body
+    # Body leading. Convention: 1.4-1.55 for screen reading (Bringhurst ~1.5,
+    # NYT ~1.5, Medium ~1.58). 1.5 sits at the editorial standard.
+    line_height: 1.5
+    align: left
+
+  layout:
+    rows:
+      gap: 8.0
+    cols:
+      gap: 20.0
+    grid:
+      columns: 24
+      gap: 20.0
+    tabs:
+      bar_height: 40.0
+      active_weight: '600'
+      inactive_weight: '400'
+      title_baseline_offset: 5.0
+      font:
+        size: 14.0
+      border:
+        width: 0.0
+        color: transparent
+        radius: 4.0
+    details:
+      summary_height: 36.0
+      arrow:
+        x: 14.0
+        font:
+          size: 13.0
+      label_x: 32.0
+      text_baseline_offset: 5.0
+      content_y_offset: 4.0
+      font:
+        size: 14.0
+      border:
+        width: 0.0
+        color: transparent
+        radius: 4.0
+
+  variables:
+    visible: true
+    # title-inline is the structural default: face title left, variable controls
+    # right, baselines aligned on one horizontal band. Untitled faces fall back
+    # to a standalone variables band (render path in faces.py guards on
+    # `_face_uses_title_inline_band`, which requires both title and variables).
+    position: title-inline
+    title_inline_title_max_width: 0.0
+    gap: 10.0
+    label_position: inline
+    line_height: 24.0
+    padding: 4.0
+    container_height: 36.0
+    container_padding: 8.0
+    control_gap: 8.0
+    # Subtle off-card surface for the daterange popover's preset rail.
+    # Warm-canvas themes (cream) override to dft-creams.surface-subtle
+    # so the rail reads as the cream canvas peeking past the white popover.
+    popover_rail_background: dft-grays.surface-subtle
+    font:
+      size:  *size_body
+    label:
+      font:
+        weight: 500
+        case: title
+    value:
+      font:
+        weight: 400
+      numeric_variant: tabular-nums
+    placeholder:
+      # Unselected/hint text reads lighter than selected-value text so the
+      # variable strip is scannable. `disabled` is the ramp ladder step
+      # semantically for hint / not-your-data text.
+      font:
+        color: dft-grays.disabled
+    border:
+      width: 0.0
+      radius: 4.0
+    input:
+      height: 32.0
+      # transparent: lets faces paint a continuous header band that shows
+      # through the variables strip; faces (or sibling themes) that want
+      # an opaque input bg should set this explicitly.
+      background: transparent
+      padding:
+        top: 4.0
+        right: 8.0
+        bottom: 4.0
+        left: 8.0
+      widths:
+        text: 150.0
+        number: 80.0
+        range: 120.0
+        slider_value_min: 30.0
+        checkbox: 16.0
+        # Chip is icon + compact label (e.g. "9–28 Apr 2026"); not a full text input.
+        daterange: 168.0
+      range:
+        default_min: 0.0
+        default_max: 100.0
+        default_step: 1.0
+      border:
+        width: 1.0
+        radius: 4.0
+
+  placeholder:
+    opacity: 0.4
+    overlay:
+      text: 'add data'
+      font:
+        size: 16
+        weight: 500