Skip to content

feat(page): ship DocsUI::Table + DocsUI::PropTable — stop hand-rolling tables - #28

Merged
mhenrixon merged 1 commit into
mainfrom
issue-11-docs-ui-table
Jul 3, 2026
Merged

feat(page): ship DocsUI::Table + DocsUI::PropTable — stop hand-rolling tables#28
mhenrixon merged 1 commit into
mainfrom
issue-11-docs-ui-table

Conversation

@mhenrixon

Copy link
Copy Markdown
Collaborator

Closes #11 (Part of #8, Phase 1).

Problem

Reference tables were the most duplicated markup in the ecosystem: the gem's own docs carried a page-local PropTable explicitly marked "Not part of the DocsUI kit", and every consuming site hand-rolled its own table/tr/td blocks. None could get an options/params/errors table from the gem.

What changed

Upstreams the dogfooded design into the kit, generalized:

  • DocsUI::Table.new(headers, rows) — generic headers + rows in the kit's daisyUI look (table table-sm table-zebra inside a rounded-box border, not-prose). Cell values follow the proven convention:
    • String → plain, Phlex-escaped text
    • [:code, "x"] → inline <code>
    • [:md, "…"] → inline GFM through DocsUI::Markdown (opt-in, so a plain string that merely looks like markdown is never surprise-parsed)
  • DocsUI::PropTable.new(rows, headers:) — a thin preset built ON Table (composition, no markup duplication): first column auto code-styled, Option/Type/Default/Description headers by default, overridable via headers:.
  • DocsUI::Markdown.inline — a no-wrapper, no-<p> render used by [:md, …] cells. Adjacent top-level paragraphs are space-joined so unwrapping never fuses text.

Both are kit-form-callable (DocsUI::Table(...) / DocsUI::PropTable(...)) automatically via include DocsUI.

Delta for a consuming site

New components, fully backwards compatible — nothing existing changes. A site can now render an args/options table from the gem instead of hand-writing daisyUI table markup.

Cleanup in this repo

  • Deletes the page-local Views::Docs::Pages::PropTable.
  • Swaps all 18 PropTable.new call sites across 7 docs pages to DocsUI::PropTable (the constructor flips from (headers, rows) to (rows, headers:); the default headers are dropped where they were the default).
  • Documents Table + PropTable on the components reference page (with a live demo of all three cell types) and in the README component table.

Test plan

Spec Covers
spec/docs_ui/table_spec.rb headers→th, rows→td, [:code]<code>, [:md]→inline markdown, empty rows → headers only, HTML in a string cell / header escaped
spec/docs_ui/prop_table_spec.rb first column code-styled, default + custom headers, [:code]/[:md] honored in other columns, reuses Table's wrapper
spec/docs_ui/markdown_spec.rb .inline: no <p>/Prose wrapper, soft break → one space, multiple paragraphs separated (regression against a "onepara" fusion bug caught in adversarial review)

Verification

  • bundle exec rspec — 121 examples, 0 failures
  • bundle exec rubocop — 48 files, no offenses
  • cd docs && bun run build:css — clean; table-zebra/rounded-box/not-prose present in the built CSS
  • Rendered /docs/configuration + all 7 swapped pages via a real HTTP request — HTTP 200, tables identical to before the swap
  • No page-local PropTable references remain

Out of scope (per the issue)

  • FieldTable/ErrorTable API presets (Phase 2 — they build on this).
  • Sortable/filterable tables (would violate the one-controller rule).
  • Fixing consumer repos' hand-rolled tables (follow-up once this ships).

…ocal one

## Summary
Upstreams the dogfooded reference-table design into the kit so every docs site
stops hand-rolling `table`/`tr`/`td` markup:

- `DocsUI::Table.new(headers, rows)` — generic headers + rows in the kit's
  daisyUI look (`table table-sm table-zebra` in a `rounded-box` border,
  `not-prose`). Cell values: `String` (plain, escaped), `[:code, "x"]` (inline
  code), `[:md, "…"]` (inline GFM through `DocsUI::Markdown`).
- `DocsUI::PropTable.new(rows, headers:)` — a thin preset built ON `Table`
  (composition, no markup duplication): name/type/default/description, first
  column auto code-styled, `Option/Type/Default/Description` headers by default,
  overridable via `headers:`.
- `DocsUI::Markdown.inline` — a no-wrapper, no-`<p>` render for `[:md, …]` cells;
  adjacent top-level paragraphs are space-joined so unwrapping never fuses text.

Deletes the page-local `Views::Docs::Pages::PropTable` ("Not part of the DocsUI
kit") and swaps all 18 call sites across 7 docs pages to `DocsUI::PropTable`.
Documents both components on the components reference page (with a live demo of
all three cell types) and the README component table.

## Test Coverage
- spec/docs_ui/table_spec.rb — headers→th, rows→td, [:code]→<code>, [:md]→inline
  markdown, empty rows → headers only, HTML in a string cell / header escaped.
- spec/docs_ui/prop_table_spec.rb — first column code-styled, default + custom
  headers, [:code]/[:md] honored in other columns, reuses Table's wrapper.
- spec/docs_ui/markdown_spec.rb — .inline: no <p>/Prose wrapper, soft break → one
  space, multiple paragraphs separated (regression: no "onepara" fusion).

## Verification
- [x] bundle exec rspec — 121 examples, 0 failures
- [x] bundle exec rubocop — 48 files, no offenses
- [x] cd docs && bun run build:css — clean; table-zebra/rounded-box/not-prose present
- [x] Rendered /docs/configuration + all 7 swapped pages — HTTP 200, tables intact
- [x] No page-local PropTable references remain

Closes #11
@mhenrixon mhenrixon assigned mhenrixon and unassigned mhenrixon Jul 3, 2026
@mhenrixon mhenrixon added the enhancement New feature or request label Jul 3, 2026
@mhenrixon
mhenrixon merged commit b6497a3 into main Jul 3, 2026
3 checks passed
@mhenrixon
mhenrixon deleted the issue-11-docs-ui-table branch July 4, 2026 14:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(table): ship DocsUI::Table + DocsUI::PropTable — stop hand-rolling tables

1 participant