fix(docs) :: address documentation gaps by 81reap · Pull Request #1390 · sqlpage/SQLPage

81reap · 2026-08-17T21:24:02Z

Addresses #1387

81reap · 2026-08-17T21:31:12Z

+-- Every component whose `id` and `class` properties behave in the ordinary way
+-- is documented from the lists below, so that the wording stays identical
+-- across components and so that the (component, top_level, name) primary key
+-- of `parameter` is not violated.
+--
+-- A handful of components deliberately document `id` or `class` in their own
+-- migration instead, because the generic wording would be wrong for them:
+-- `modal` (`id` is required, and is what a button targets), `form` (`id` is
+-- what an outside submit button references), `foldable` (top level and item
+-- level mean different things) and `button` (`id` lands on each button, not on
+-- the container). Do not duplicate those here.


I decided to keep the top level comments for context. I can remove them in a rev2 if needed :)

lovasoa · 2026-08-18T10:52:59Z

There is a lot to review here. Are you certain this does not contain any hallucination ?

81reap · 2026-08-18T12:53:47Z

+    ('validate_shape', 'The shape of the validation button (e.g., pill, square).', 'TEXT', TRUE, TRUE),
+    ('validate_size', 'The size of the validation button (e.g., sm, lg).', 'TEXT', TRUE, TRUE),


SQLPage/sqlpage/templates/form.handlebars

Lines 168 to 170 in 6859b56

{{#if validate_shape}} btn-{{validate_shape}} {{/if}}

{{#if validate_outline}} btn-outline-{{validate_outline}} {{/if}}

{{#if validate_size}} btn-{{validate_size}} {{/if}}"

81reap · 2026-08-18T12:54:18Z

+    ('reset_outline', 'A color to outline the reset button.', 'COLOR', TRUE, TRUE),
+    ('reset_shape', 'The shape of the reset button (e.g., pill, square).', 'TEXT', TRUE, TRUE),
+    ('reset_size', 'The size of the reset button (e.g., sm, lg).', 'TEXT', TRUE, TRUE),


SQLPage/sqlpage/templates/form.handlebars

Lines 182 to 185 in 6859b56

{{#if reset_color}} btn-{{reset_color}} {{/if}}

{{#if reset_shape}} btn-{{reset_shape}} {{/if}}

{{#if reset_outline}} btn-outline-{{reset_outline}} {{/if}}

{{#if reset_size}} btn-{{reset_size}} {{/if}}"

81reap · 2026-08-18T12:54:49Z

+    ('reset_outline', 'A color to outline the reset button.', 'COLOR', TRUE, TRUE),
+    ('reset_shape', 'The shape of the reset button (e.g., pill, square).', 'TEXT', TRUE, TRUE),
+    ('reset_size', 'The size of the reset button (e.g., sm, lg).', 'TEXT', TRUE, TRUE),
+    ('narrow', 'Whether to trim the horizontal padding between the icon and the label of the validation and reset buttons.', 'BOOLEAN', TRUE, TRUE),


SQLPage/sqlpage/templates/form.handlebars

Line 174 in 6859b56

<span {{~#if (not narrow)}} class="me-1"{{/if}}>{{~icon_img validate_icon~}}</span>

SQLPage/sqlpage/templates/form.handlebars

Line 188 in 6859b56

<span {{~#if (not narrow)}} class="me-1"{{/if}}>{{~icon_img reset_icon~}}</span>

81reap · 2026-08-18T12:56:10Z

+    ('formmethod', 'When type is "submit", the HTTP method to submit the form with. Takes precedence over the form''s own "method".', 'TEXT', FALSE, TRUE),
+    ('formnovalidate', 'When type is "submit", skips the browser''s validation of the other fields when this button submits the form.', 'BOOLEAN', FALSE, TRUE),
+    ('formtarget', 'When type is "submit", where to display the response. Takes the same values as a link target: "_blank" to open a new tab, "_self" to stay in the same one.', 'TEXT', FALSE, TRUE),


SQLPage/sqlpage/templates/form.handlebars

Lines 130 to 132 in 6859b56

{{~#if formenctype}}formenctype="{{formenctype}}" {{/if~}}

{{~#if formmethod}}formmethod="{{formmethod}}" {{/if~}}

{{~#if formnovalidate}}formnovalidate="{{formnovalidate}}" {{/if~}}

81reap · 2026-08-18T12:56:18Z

+    ('formnovalidate', 'When type is "submit", skips the browser''s validation of the other fields when this button submits the form.', 'BOOLEAN', FALSE, TRUE),
+    ('formtarget', 'When type is "submit", where to display the response. Takes the same values as a link target: "_blank" to open a new tab, "_self" to stay in the same one.', 'TEXT', FALSE, TRUE),
+    ('accept', 'Used only for inputs of type "file". A comma-separated list of the file types the user can pick, given as extensions (".pdf,.png") or as MIME types ("image/*").', 'TEXT', FALSE, TRUE),
+    ('list', 'The id of a datalist element holding the suggestions to show for this field. The datalist itself has to be rendered by the "html" component.', 'TEXT', FALSE, TRUE),


SQLPage/sqlpage/templates/form.handlebars

Line 134 in 6859b56

{{~#if list}}list="{{list}}" {{/if~}}

81reap · 2026-08-18T12:56:26Z

+    ('formmethod', 'When type is "submit", the HTTP method to submit the form with. Takes precedence over the form''s own "method".', 'TEXT', FALSE, TRUE),
+    ('formnovalidate', 'When type is "submit", skips the browser''s validation of the other fields when this button submits the form.', 'BOOLEAN', FALSE, TRUE),
+    ('formtarget', 'When type is "submit", where to display the response. Takes the same values as a link target: "_blank" to open a new tab, "_self" to stay in the same one.', 'TEXT', FALSE, TRUE),
+    ('accept', 'Used only for inputs of type "file". A comma-separated list of the file types the user can pick, given as extensions (".pdf,.png") or as MIME types ("image/*").', 'TEXT', FALSE, TRUE),


SQLPage/sqlpage/templates/form.handlebars

Line 136 in 6859b56

{{~#if accept}}accept="{{accept}}" {{/if~}}

81reap · 2026-08-18T12:56:50Z

    ('ytitle', 'Title of the y axis, displayed to its left.', 'TEXT', TRUE, TRUE),
    ('ztitle', 'Title of the z axis, displayed in tooltips.', 'TEXT', TRUE, TRUE),
    ('xticks', 'Number of ticks on the x axis.', 'INTEGER', TRUE, TRUE),
+    ('yticks', 'Number of ticks on the y axis.', 'INTEGER', TRUE, TRUE),


SQLPage/sqlpage/templates/chart.handlebars

Line 27 in 6859b56

"yticks": {{stringify yticks}},

81reap · 2026-08-18T12:57:04Z

    -- item level
    ('x', 'The value of the point on the horizontal axis', 'REAL', FALSE, FALSE),
    ('y', 'The value of the point on the vertical axis', 'REAL', FALSE, FALSE),
+    ('z', 'A third value carried by the point. Used as the bubble radius in a bubble chart, and shown in the tooltip under the name given by the top-level "ztitle".', 'REAL', FALSE, TRUE),


SQLPage/sqlpage/templates/chart.handlebars

Line 47 in 6859b56

{{~#if z}}, {{~ stringify z ~}} {{~/if~}}

81reap · 2026-08-18T12:57:29Z

    ('money', 'Name of a numeric column whose values should be displayed as currency amounts, in the currency defined by the `currency` property. This argument can be repeated multiple times.', 'TEXT', TRUE, TRUE),
    ('currency', 'The ISO 4217 currency code (e.g., USD, EUR, GBP, etc.) to use when formatting monetary values.', 'TEXT', TRUE, TRUE),
    ('number_format_digits', 'Maximum number of decimal digits to display for numeric values.', 'INTEGER', TRUE, TRUE),
+    ('number_format_locale', 'A BCP 47 language tag (e.g. "de-DE", "en-IN") deciding how numbers and monetary values are formatted. Defaults to the locale of the visitor''s browser.', 'TEXT', TRUE, TRUE),


SQLPage/sqlpage/templates/table.handlebars

Line 27 in 6859b56

{{~#if number_format_locale}} data-number_format_locale="{{number_format_locale}}"{{/if~}}

81reap · 2026-08-18T12:57:51Z

    ('navbar_title', 'The title to display in the top navigation bar. Used to display a different title in the top menu than the one that appears in the tab of the browser.', 'TEXT', TRUE, TRUE),
-    ('target', '"_blank" to open the link in a new tab, "_self" to open it in the same tab, "_parent" to open it in the parent frame, or "_top" to open it in the full body of the window', 'TEXT', TRUE, TRUE)
+    ('target', 'Where the menu items should open: "_blank" for a new tab, "_self" for the same tab, "_parent" for the parent frame, or "_top" for the full body of the window. Set it inside a "menu_item" json object; it has no effect when set directly on the shell.', 'TEXT', TRUE, TRUE),
+    ('class', 'class attribute added to the page''s html element. It can be used to apply custom styling to the whole page through css.', 'TEXT', TRUE, TRUE)


SQLPage/sqlpage/templates/table.handlebars

Line 27 in 6859b56

{{~#if number_format_locale}} data-number_format_locale="{{number_format_locale}}"{{/if~}}

81reap · 2026-08-18T12:58:13Z

+            (
+                'color',
+                'Color of the badge behind the feature section''s icon. Defaults to "success".',
+                'COLOR',
+                FALSE,
+                TRUE
+            ),


SQLPage/sqlpage/templates/hero.handlebars

Line 38 in 6859b56

<div style="margin-top: -1.5rem;" class="badge bg-{{default color 'success'}} text-{{default color 'success'}}-fg fs-1 mb-4 p-2">

81reap · 2026-08-18T12:59:26Z

+    (
+        'map',
+        'title',
+        'A text header displayed above the map.',
+        'TEXT',
+        TRUE,
+        TRUE
+    ),


SQLPage/sqlpage/templates/map.handlebars

Line 3 in 6859b56

<h3 class="card-title">{{title}}</h3>

81reap · 2026-08-18T12:59:38Z

+    (
+        'tab',
+        'center',
+        'Whether this individual tab''s label should be centered inside the tab. Defaults to false.',
+        'BOOLEAN',
+        FALSE,
+        TRUE


SQLPage/sqlpage/templates/tab.handlebars

Line 9 in 6859b56

{{~/if}} {{#if center~}}

81reap · 2026-08-18T13:00:32Z

+    ('height', 'Height of the iframe embed code, in pixels. Used only when embed_mode is ''iframe''.', 'INTEGER', FALSE, TRUE),
+    ('allow', 'The permissions policy of the iframe embed code, for instance "fullscreen; clipboard-write". Used only when embed_mode is ''iframe''.', 'TEXT', FALSE, TRUE),
+    ('sandbox', 'The restrictions to apply to the iframe embed code, for instance "allow-scripts allow-same-origin". Used only when embed_mode is ''iframe''.', 'TEXT', FALSE, TRUE),


SQLPage/sqlpage/templates/card.handlebars

Lines 57 to 62 in 6859b56

{{~#if (eq embed_mode "iframe")}}

<iframe src="{{embed}}"

width="{{#if width}}{{width}}{{else}}100%{{/if}}"

{{~#if height}} height="{{height}}"{{/if~}}

{{~#if allow}} allow="{{allow}}"{{/if~}}

{{~#if sandbox}} sandbox="{{sandbox}}"{{/if~}}

81reap · 2026-08-18T13:00:54Z

+),(
+    'rss',
+    'sub_category',
+    'Defines a sub-category, nested inside the "category". Ignored unless "category" is also set.',
+    'TEXT',
+    TRUE,
+    TRUE
 ),(


SQLPage/sqlpage/templates/rss.handlebars

Line 12 in 6859b56

{{~#if category}}<itunes:category text="{{category}}">{{sub_category}}</itunes:category>{{/if}}

81reap · 2026-08-18T13:01:10Z

+),(
+    'rss',
+    'funding_text',
+    'The text to display with the donation/funding link. Ignored unless "funding_url" is also set.',
+    'TEXT',
+    TRUE,
+    TRUE


SQLPage/sqlpage/templates/rss.handlebars

Line 17 in 6859b56

{{~#if funding_url}}<podcast:funding url="{{funding_url}}">{{funding_text}}</podcast:funding>{{/if}}

81reap · 2026-08-18T13:01:33Z

    ('icon','Name of an icon to be displayed on the top of the empty state.','ICON',TRUE,TRUE),
    ('image','The URL (absolute or relative) of an image to display at the top of the empty state.','URL',TRUE,TRUE),
    ('description','A short text displayed below the title.','TEXT',TRUE,TRUE),
+    ('description_md','A short text displayed below the title, formatted using markdown.','TEXT',TRUE,TRUE),


SQLPage/sqlpage/templates/empty_state.handlebars

Lines 18 to 19 in 6859b56

{{~#if description_md~}}

{{{markdown description_md}}}

81reap · 2026-08-18T13:02:25Z

@lovasoa I tried to add a test file where I could. Not sure if there's a better way that we can test SQL files to be able to statically validate documentation.

I've added comments to the CR pointing to where in the code the variable is referenced. let me know if that helps! :)

fix(docs) :: address documentation gaps

c8ebfe0

81reap commented Aug 17, 2026

View reviewed changes

81reap mentioned this pull request Aug 18, 2026

Improve Codebase :: Documentation Drift #1387

Open

81reap commented Aug 18, 2026

View reviewed changes

		('validate_shape', 'The shape of the validation button (e.g., pill, square).', 'TEXT', TRUE, TRUE),
		('validate_size', 'The size of the validation button (e.g., sm, lg).', 'TEXT', TRUE, TRUE),

	{{#if validate_shape}} btn-{{validate_shape}} {{/if}}
	{{#if validate_outline}} btn-outline-{{validate_outline}} {{/if}}
	{{#if validate_size}} btn-{{validate_size}} {{/if}}"

	{{#if reset_color}} btn-{{reset_color}} {{/if}}
	{{#if reset_shape}} btn-{{reset_shape}} {{/if}}
	{{#if reset_outline}} btn-outline-{{reset_outline}} {{/if}}
	{{#if reset_size}} btn-{{reset_size}} {{/if}}"

	{{~#if formenctype}}formenctype="{{formenctype}}" {{/if~}}
	{{~#if formmethod}}formmethod="{{formmethod}}" {{/if~}}
	{{~#if formnovalidate}}formnovalidate="{{formnovalidate}}" {{/if~}}

	{{~#if (eq embed_mode "iframe")}}
	<iframe src="{{embed}}"
	width="{{#if width}}{{width}}{{else}}100%{{/if}}"
	{{~#if height}} height="{{height}}"{{/if~}}
	{{~#if allow}} allow="{{allow}}"{{/if~}}
	{{~#if sandbox}} sandbox="{{sandbox}}"{{/if~}}

Uh oh!

Uh oh!

Conversation

81reap commented Aug 17, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lovasoa commented Aug 18, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

81reap commented Aug 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants