diff --git a/AGENTS.md b/AGENTS.md index 33796920..01ce95ee 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -128,12 +128,14 @@ For dynamic frontend changes, run the Playwright tests under `tests/end-to-end/` Components and functions are documented in [official-site migrations](./examples/official-site/sqlpage/migrations/). Edit the existing migration for an existing entity; add an appropriately ordered migration for a new entity. The official-site database is recreated from migrations on each deployment. official documentation website sql tables: - - `parameter_type(type)` + - `parameter_type(name)` -- the allowed values of `parameter.type` - `component(name,description,icon,introduced_in_version)` -- icon name from tabler icon - - `parameter(top_level BOOLEAN, name, component REFERENCES component(name), description, description_md, type, optional BOOLEAN)` parameter types: BOOLEAN, COLOR, HTML, ICON, INTEGER, JSON, REAL, TEXT, TIMESTAMP, URL + - `parameter(top_level BOOLEAN, name, component REFERENCES component(name), description, description_md, type REFERENCES parameter_type(name), optional BOOLEAN)` parameter types: BOOLEAN, COLOR, HTML, ICON, INTEGER, JSON, REAL, TEXT, TIMESTAMP, URL. Set exactly one of `description` (plain text) and `description_md` (markdown). - `example(component REFERENCES component(name), description, properties JSON)` - `sqlpage_functions(name,icon,description_md,return_type,introduced_in_version)` - `sqlpage_function_parameters(function,index,name,description_md,type)` + - `blog_posts(title,description,icon,external_url,content,created_at)` -- release announcements and long-form guides + - `example_cards(title,folder,db_engine,description)` #### Project Conventions diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f2d86528..f764460e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -51,24 +51,27 @@ Windows comes with ODBC pre-installed; SQLPage cannot statically link to the uni ### Rust -- Use `cargo fmt` to format your Rust code +- Use `cargo fmt --all` to format your Rust code - Run `cargo clippy` to catch common mistakes and improve code quality - All code must pass the following checks: ```bash cargo fmt --all -- --check -cargo clippy +cargo clippy --all-targets --all-features -- -D warnings ``` ### Frontend -We use Biome for linting and formatting of the frontend code. +We use Biome for linting and formatting of the frontend code, and TypeScript +to typecheck it. ```bash -npx @biomejs/biome check . +npm install # once +npm run format # apply formatting +npm test # the check CI runs: biome, typecheck, and the frontend unit tests ``` -This will check the entire codebase (html, css, js). +`npm test` checks the entire frontend codebase (html, css, js, ts). ## Testing @@ -127,7 +130,11 @@ INSERT INTO component(name, icon, description, introduced_in_version) VALUES -- Document all parameters INSERT INTO parameter(component, name, description, type, top_level, optional) -VALUES ('component_name', 'param_name', 'param_description', 'TEXT|BOOLEAN|NUMBER|JSON|ICON|COLOR', false, true); +VALUES ('component_name', 'param_name', 'param_description', 'TEXT|BOOLEAN|INTEGER|JSON|ICON|COLOR|HTML|REAL|TIMESTAMP|URL', false, true); + +-- Use description_md instead of description when the text contains markdown +INSERT INTO parameter(component, name, description_md, type, top_level, optional) +VALUES ('component_name', 'other_param', 'Set to `true` to see [the docs](/documentation.sql).', 'BOOLEAN', true, true); -- Include usage examples INSERT INTO example(component, description, properties) VALUES @@ -180,7 +187,7 @@ VALUES ( 1, 'parameter_name', 'Description of what this parameter does and how to use it.', - 'TEXT|BOOLEAN|NUMBER|JSON' + 'TEXT|BOOLEAN|INTEGER|JSON' ); ``` @@ -208,6 +215,7 @@ git checkout -b feature/your-feature-name - Code is properly formatted - New features are documented - tests cover new functionality +- `CHANGELOG.md` has an entry for any user-visible change 3. Push your changes and create a Pull Request @@ -216,8 +224,8 @@ git checkout -b feature/your-feature-name - Run Rust formatting and clippy checks - Execute all tests across multiple platforms (Linux, Windows) - Build Docker images for multiple architectures - - Run frontend linting with Biome - - Test against multiple databases (PostgreSQL, MySQL, MSSQL) + - Run frontend linting, typechecking and unit tests (`npm test`) + - Test against multiple databases (SQLite, PostgreSQL, MySQL, MSSQL, Oracle, and ODBC) ## Release Process diff --git a/examples/official-site/component.sql b/examples/official-site/component.sql index c10943f3..53453fe3 100644 --- a/examples/official-site/component.sql +++ b/examples/official-site/component.sql @@ -30,17 +30,17 @@ where name = $component and introduced_in_version IS NOT NULL; select 'title' as component, 3 as level, 'Top-level parameters' as contents where $component IS NOT NULL; select 'table' as component, true as striped, true as hoverable, true as freeze_columns, - 'type' as markdown + 'type' as markdown, 'description' as markdown where $component IS NOT NULL; select name, CASE WHEN optional THEN '' ELSE 'REQUIRED' END as required, - CASE type + CASE type WHEN 'COLOR' THEN printf('[%s](/colors.sql)', type) WHEN 'ICON' THEN printf('[%s](https://tabler-icons.io/?ref=sqlpage)', type) ELSE type END AS type, - description + coalesce(description_md, description) as description from parameter where component = $component AND top_level ORDER BY optional, name; @@ -48,17 +48,17 @@ ORDER BY optional, name; select 'title' as component, 3 as level, 'Row-level parameters' as contents WHERE $component IS NOT NULL AND EXISTS (SELECT 1 from parameter where component = $component AND NOT top_level); select 'table' as component, true as striped, true as hoverable, true as freeze_columns, - 'type' as markdown + 'type' as markdown, 'description' as markdown where $component IS NOT NULL; select name, CASE WHEN optional THEN '' ELSE 'REQUIRED' END as required, - CASE type + CASE type WHEN 'COLOR' THEN printf('[%s](/colors.sql)', type) WHEN 'ICON' THEN printf('[%s](https://tabler-icons.io/?ref=sqlpage)', type) ELSE type END AS type, - description + coalesce(description_md, description) as description from parameter where component = $component AND NOT top_level ORDER BY optional, name; diff --git a/examples/official-site/sqlpage/migrations/01_documentation.sql b/examples/official-site/sqlpage/migrations/01_documentation.sql index 9e4ce254..3491c5cf 100644 --- a/examples/official-site/sqlpage/migrations/01_documentation.sql +++ b/examples/official-site/sqlpage/migrations/01_documentation.sql @@ -43,7 +43,7 @@ INSERT INTO parameter(component, name, description, type, top_level, optional) S -- item level ('title', 'Name of the list item, displayed prominently.', 'TEXT', FALSE, FALSE), ('description', 'A description of the list item, displayed as greyed-out text.', 'TEXT', FALSE, TRUE), - ('description_md', 'A description of the list item, displayed as greyed-out text, in Markdown format, allowing you to use rich text formatting, including **bold** and *italic* text.', 'TEXT', FALSE, TRUE), + ('description_md', 'A description of the list item, displayed as greyed-out text, in Markdown format, allowing you to use rich text formatting, including `**bold**` and `*italic*` text.', 'TEXT', FALSE, TRUE), ('link', 'An URL to which the user should be taken when they click on the list item.', 'URL', FALSE, TRUE), ('icon', 'Name of an icon to display on the left side of the item.', 'ICON', FALSE, TRUE), ('image_url', 'The URL of a small image to display on the left side of the item.', 'URL', FALSE, TRUE), @@ -146,14 +146,13 @@ INSERT INTO parameter(component, name, description, type, top_level, optional) S -- top level ('title', 'Text header before the paragraph.', 'TEXT', TRUE, TRUE), ('center', 'Whether to center the title.', 'BOOLEAN', TRUE, TRUE), - ('width', 'How wide the paragraph should be, in characters.', 'INTEGER', TRUE, TRUE), ('html', 'Raw html code to include on the page. Don''t use that if you are not sure what you are doing, it may have security implications.', 'TEXT', TRUE, TRUE), ('contents', 'A top-level paragraph of text to display, without any formatting, without having to make additional queries.', 'TEXT', TRUE, TRUE), - ('contents_md', 'Rich text in the markdown format. Among others, this allows you to write bold text using **bold**, italics using *italics*, and links using [text](https://example.com).', 'TEXT', TRUE, TRUE), + ('contents_md', 'Rich text in the markdown format. Among others, this allows you to write bold text using `**bold**`, italics using `*italics*`, and links using `[text](https://example.com)`.', 'TEXT', TRUE, TRUE), ('article', 'Makes long texts more readable by increasing the line height, adding margins, using a serif font, and decorating the initial letter.', 'BOOLEAN', TRUE, TRUE), -- item level ('contents', 'A span of text to display', 'TEXT', FALSE, FALSE), - ('contents_md', 'Rich text in the markdown format. Among others, this allows you to write bold text using **bold**, italics using *italics*, and links using [text](https://example.com).', 'TEXT', FALSE, TRUE), + ('contents_md', 'Rich text in the markdown format. Among others, this allows you to write bold text using `**bold**`, italics using `*italics*`, and links using `[text](https://example.com)`.', 'TEXT', FALSE, TRUE), ('link', 'An URL to which the user should be taken when they click on this span of text.', 'URL', FALSE, TRUE), ('color', 'The name of a color for this span of text.', 'COLOR', FALSE, TRUE), ('underline', 'Whether the span of text should be underlined.', 'BOOLEAN', FALSE, TRUE), @@ -264,12 +263,18 @@ INSERT INTO parameter(component, name, description, type, top_level, optional) S ('validate', 'The text to display in the button at the bottom of the form that submits the values. Omit this property to let the browser display the default form validation text, or set it to the empty string to remove the button completely.', 'TEXT', TRUE, TRUE), ('validate_color', 'The color of the button at the bottom of the form that submits the values. Omit this property to use the default color.', 'COLOR', TRUE, TRUE), ('validate_outline', 'A color to outline the validation button.', 'COLOR', TRUE, TRUE), + ('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), ('reset', 'The text to display in the button at the bottom of the form that resets the form to its original state. Omit this property not to show a reset button at all.', 'TEXT', TRUE, TRUE), ('id', 'A unique identifier for the form, which can then be used to validate the form from a button outside of the form.', 'TEXT', TRUE, TRUE), ('auto_submit', 'Automatically submit the form when the user changes any of its fields, and remove the validation button.', 'BOOLEAN', TRUE, TRUE), ('validate_icon', 'Name of an icon to be displayed on the left side of the submit button.', 'ICON', TRUE, TRUE), ('reset_icon', 'Name of an icon to be displayed on the left side of the reset button.', 'ICON', TRUE, TRUE), ('reset_color', 'The color of the button at the bottom of the form that resets the form to its original state. Omit this property to use the default color.', 'COLOR', TRUE, TRUE), + ('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), -- item level ('type', 'Declares input control behavior and expected format. All HTML input types are supported (text, number, date, file, checkbox, radio, hidden, ...). SQLPage adds some custom types: textarea, switch, header. text by default. See https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#input_types', 'TEXT', FALSE, TRUE), ('name', 'The name of the input field, that you can use in the target page to get the value the user entered for the field.', 'TEXT', FALSE, FALSE), @@ -297,6 +302,11 @@ INSERT INTO parameter(component, name, description, type, top_level, optional) S ('minlength', 'Minimum length of text allowed in the field.', 'INTEGER', FALSE, TRUE), ('maxlength', 'Maximum length of text allowed in the field.', 'INTEGER', FALSE, TRUE), ('formaction', 'When type is "submit", this specifies the URL of the file that will handle the form submission. Useful when you need multiple submit buttons.', 'TEXT', FALSE, TRUE), + ('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), + ('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), ('class', 'A CSS class to apply to the form element.', 'TEXT', FALSE, TRUE), ('prefix_icon','Icon to display on the left side of the input field, on the same line.','ICON',FALSE,TRUE), ('prefix','Text to display on the left side of the input field, on the same line.','TEXT',FALSE,TRUE), @@ -660,6 +670,7 @@ INSERT INTO parameter(component, name, description, type, top_level, optional) S ('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), ('ystep', 'Step between ticks on the y axis.', 'REAL', TRUE, TRUE), ('marker', 'Marker size', 'REAL', TRUE, TRUE), ('labels', 'Whether to show the data labels on the chart or not.', 'BOOLEAN', TRUE, TRUE), @@ -673,6 +684,7 @@ INSERT INTO parameter(component, name, description, type, top_level, optional) S -- 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), ('label', 'An alias for parameter "x"', 'REAL', FALSE, TRUE), ('value', 'An alias for parameter "y"', 'REAL', FALSE, TRUE), ('series', 'If multiple series are represented and share the same y-axis, this parameter can be used to distinguish between them.', 'TEXT', FALSE, TRUE) @@ -829,6 +841,7 @@ INSERT INTO parameter(component, name, description, type, top_level, optional) S ('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), ('edit_url', 'If set, an edit button will be added to each row. The value of this property should be a URL, possibly containing the `{id}` placeholder that will be replaced by the value of the `_sqlpage_id` property for that row. Clicking the edit button will take the user to that URL. Added in v0.39.0', 'TEXT', TRUE, TRUE), ('delete_url', 'If set, a delete button will be added to each row. The value of this property should be a URL, possibly containing the `{id}` placeholder that will be replaced by the value of the `_sqlpage_id` property for that row. Clicking the delete button will take the user to that URL. Added in v0.39.0', 'TEXT', TRUE, TRUE), ('custom_actions', 'If set, a column of custom action buttons will be added to each row. The value of this property should be a JSON array of objects, each object defining a button with the following properties: `name` (the text to display on the button), `icon` (the tabler icon name or image link to display on the button), `link` (the URL to navigate to when the button is clicked, possibly containing the `{id}` placeholder that will be replaced by the value of the `_sqlpage_id` property for that row), and `tooltip` (optional text to display when hovering over the button). Added in v0.39.0', 'JSON', TRUE, TRUE), @@ -1367,7 +1380,8 @@ INSERT INTO parameter(component, name, description, type, top_level, optional) S ('footer', 'Muted text to display in the footer of the page. This can be used to display a link to the terms and conditions of your application, for instance. By default, shows "Built with SQLPage". Supports links with markdown.', 'TEXT', TRUE, TRUE), ('preview_image', 'The URL of an image to display as a link preview when the page is shared on social media', 'URL', TRUE, TRUE), ('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) ) x; INSERT INTO example(component, description, properties) VALUES diff --git a/examples/official-site/sqlpage/migrations/02_hero_component.sql b/examples/official-site/sqlpage/migrations/02_hero_component.sql index d528453b..ad41d06e 100644 --- a/examples/official-site/sqlpage/migrations/02_hero_component.sql +++ b/examples/official-site/sqlpage/migrations/02_hero_component.sql @@ -126,6 +126,13 @@ FROM FALSE, TRUE ), + ( + 'color', + 'Color of the badge behind the feature section''s icon. Defaults to "success".', + 'COLOR', + FALSE, + TRUE + ), ( 'link', 'An URL to which the user should be taken when they click on the section title.', diff --git a/examples/official-site/sqlpage/migrations/03_alert_component.sql b/examples/official-site/sqlpage/migrations/03_alert_component.sql index 0313bcda..92e672c2 100644 --- a/examples/official-site/sqlpage/migrations/03_alert_component.sql +++ b/examples/official-site/sqlpage/migrations/03_alert_component.sql @@ -48,7 +48,7 @@ VALUES ( ( 'alert', 'description_md', - 'Detailed description or content of the alert message, in Markdown format, allowing you to use rich text formatting, including **bold** and *italic* text.', + 'Detailed description or content of the alert message, in Markdown format, allowing you to use rich text formatting, including `**bold**` and `*italic*` text.', 'TEXT', TRUE, TRUE diff --git a/examples/official-site/sqlpage/migrations/10_map.sql b/examples/official-site/sqlpage/migrations/10_map.sql index 040614c6..8ef4693b 100644 --- a/examples/official-site/sqlpage/migrations/10_map.sql +++ b/examples/official-site/sqlpage/migrations/10_map.sql @@ -37,6 +37,14 @@ INSERT INTO optional ) VALUES + ( + 'map', + 'title', + 'A text header displayed above the map.', + 'TEXT', + TRUE, + TRUE + ), ( 'map', 'latitude', diff --git a/examples/official-site/sqlpage/migrations/13_tab.sql b/examples/official-site/sqlpage/migrations/13_tab.sql index 1755404a..bccbaca2 100644 --- a/examples/official-site/sqlpage/migrations/13_tab.sql +++ b/examples/official-site/sqlpage/migrations/13_tab.sql @@ -68,6 +68,14 @@ VALUES ( 'BOOLEAN', TRUE, TRUE + ), + ( + 'tab', + 'center', + 'Whether this individual tab''s label should be centered inside the tab. Defaults to false.', + 'BOOLEAN', + FALSE, + TRUE ) ; diff --git a/examples/official-site/sqlpage/migrations/31_card_docs_update.sql b/examples/official-site/sqlpage/migrations/31_card_docs_update.sql index 3131e597..2cdaa11a 100644 --- a/examples/official-site/sqlpage/migrations/31_card_docs_update.sql +++ b/examples/official-site/sqlpage/migrations/31_card_docs_update.sql @@ -26,11 +26,14 @@ INSERT INTO parameter(component, name, description, type, top_level, optional) S ('link', 'An URL to which the user should be taken when they click on the card.', 'URL', FALSE, TRUE), ('footer_link', 'An URL to which the user should be taken when they click on the footer.', 'URL', FALSE, TRUE), ('style', 'Inline style property to your iframe embed code. For example "background-color: #FFFFFF"', 'TEXT', FALSE, TRUE), + ('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), ('icon', 'Name of an icon to display on the right side of the card.', 'ICON', FALSE, TRUE), ('color', 'The name of a color, to be displayed on the left of the card to highlight it. If the embed parameter is enabled and you don''t have a title or description, this parameter won''t apply.', 'COLOR', FALSE, TRUE), ('background_color', 'The background color of the card.', 'COLOR', FALSE, TRUE), ('active', 'Whether this item in the grid is considered "active". Active items are displayed more prominently.', 'BOOLEAN', FALSE, TRUE), - ('width', 'The width of the card, between 1 (smallest) and 12 (full-width). The default width is 3, resulting in 4 cards per line.', 'INTEGER', FALSE, TRUE) + ('width', 'The width of the card, between 1 (smallest) and 12 (full-width). The default width is 3, resulting in 4 cards per line. When embed_mode is ''iframe'', this is used as the width of the iframe instead, and defaults to 100%.', 'INTEGER', FALSE, TRUE) ) x; INSERT INTO parameter(component, name, description_md, type, top_level, optional) SELECT 'card', * FROM (VALUES ('embed', 'A url whose contents will be fetched and injected into the body of this card. diff --git a/examples/official-site/sqlpage/migrations/35_code_title.sql b/examples/official-site/sqlpage/migrations/35_code_title.sql index 75419fa8..cf296033 100644 --- a/examples/official-site/sqlpage/migrations/35_code_title.sql +++ b/examples/official-site/sqlpage/migrations/35_code_title.sql @@ -84,7 +84,7 @@ INSERT INTO parameter (component,name,description,type,top_level,optional) VALUE ),( 'code', 'description_md', - 'Rich text in the markdown format. Among others, this allows you to write bold text using **bold**, italics using *italics*, and links using [text](https://example.com).', + 'Rich text in the markdown format. Among others, this allows you to write bold text using `**bold**`, italics using `*italics*`, and links using `[text](https://example.com)`.', 'TEXT', FALSE, TRUE diff --git a/examples/official-site/sqlpage/migrations/37_rss.sql b/examples/official-site/sqlpage/migrations/37_rss.sql index 6ff2979d..6525e077 100644 --- a/examples/official-site/sqlpage/migrations/37_rss.sql +++ b/examples/official-site/sqlpage/migrations/37_rss.sql @@ -43,6 +43,13 @@ INSERT INTO parameter (component,name,description,type,top_level,optional) VALUE 'TEXT', TRUE, TRUE +),( + 'rss', + 'sub_category', + 'Defines a sub-category, nested inside the "category". Ignored unless "category" is also set.', + 'TEXT', + TRUE, + TRUE ),( 'rss', 'explicit', @@ -85,6 +92,13 @@ INSERT INTO parameter (component,name,description,type,top_level,optional) VALUE 'URL', TRUE, TRUE +),( + 'rss', + 'funding_text', + 'The text to display with the donation/funding link. Ignored unless "funding_url" is also set.', + 'TEXT', + TRUE, + TRUE ),( 'rss', 'type', diff --git a/examples/official-site/sqlpage/migrations/49_big_number.sql b/examples/official-site/sqlpage/migrations/49_big_number.sql index e18db309..17c4dccf 100644 --- a/examples/official-site/sqlpage/migrations/49_big_number.sql +++ b/examples/official-site/sqlpage/migrations/49_big_number.sql @@ -8,8 +8,7 @@ INSERT INTO component(name, icon, description, introduced_in_version) VALUES INSERT INTO parameter(component, name, description, type, top_level, optional) SELECT 'big_number', * FROM (VALUES -- Top-level parameters (for the whole big_number list) ('columns', 'The number of columns to display the big numbers in (default is one column per item).', 'INTEGER', TRUE, TRUE), - ('id', 'An optional ID to be used as an anchor for links.', 'TEXT', TRUE, TRUE), - ('class', 'An optional CSS class to be added to the component for custom styling', 'TEXT', TRUE, TRUE), + -- id and class, at both levels, come from 99_shared_id_class_attributes.sql -- Item-level parameters (for each big number) ('title', 'The title or label for the big number.', 'TEXT', FALSE, TRUE), ('title_link', 'A link for the Big Number title. If set, the entire title becomes clickable.', 'TEXT', FALSE, TRUE), diff --git a/examples/official-site/sqlpage/migrations/60_empty_state.sql b/examples/official-site/sqlpage/migrations/60_empty_state.sql index 4d897d4d..1f0b6551 100644 --- a/examples/official-site/sqlpage/migrations/60_empty_state.sql +++ b/examples/official-site/sqlpage/migrations/60_empty_state.sql @@ -11,11 +11,11 @@ INSERT INTO parameter(component, name, description, type, top_level, optional) S ('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), ('link_text','The text displayed on the button.','TEXT',TRUE,FALSE), ('link_icon','Name of an icon to be displayed on the left side of the button.','ICON',TRUE,FALSE), - ('link','The URL to which the button should navigate when clicked.','URL',TRUE,FALSE), - ('class','Class attribute added to the container in HTML. It can be used to apply custom styling to this item through css.','TEXT',TRUE,TRUE), - ('id','ID attribute added to the container in HTML. It can be used to target this item through css or for scrolling to this item through links (use "#id" in link url).','TEXT',TRUE,TRUE) + ('link','The URL to which the button should navigate when clicked.','URL',TRUE,FALSE) + -- id and class come from 99_shared_id_class_attributes.sql ) x; INSERT INTO example(component, description, properties) VALUES diff --git a/examples/official-site/sqlpage/migrations/63_modal.sql b/examples/official-site/sqlpage/migrations/63_modal.sql index dfc78c01..435b71aa 100644 --- a/examples/official-site/sqlpage/migrations/63_modal.sql +++ b/examples/official-site/sqlpage/migrations/63_modal.sql @@ -9,7 +9,7 @@ INSERT INTO parameter(component, name, description, type, top_level, optional) S ('title','Description of the modal box.','TEXT',TRUE,FALSE), ('close','The text to display in the Close button.','TEXT',TRUE,TRUE), ('contents','A paragraph of text to display, without any formatting, without having to make additional queries.','TEXT',FALSE,TRUE), - ('contents_md','Rich text in the markdown format. Among others, this allows you to write bold text using **bold**, italics using *italics*, and links using [text](https://example.com).','TEXT',FALSE,TRUE), + ('contents_md','Rich text in the markdown format. Among others, this allows you to write bold text using `**bold**`, italics using `*italics*`, and links using `[text](https://example.com)`.','TEXT',FALSE,TRUE), ('scrollable','Create a scrollable modal that allows scroll the modal body.','BOOLEAN',TRUE,TRUE), ('class','Class attribute added to the container in HTML. It can be used to apply custom styling to this item through css.','TEXT',TRUE,TRUE), ('id','ID attribute added to the container in HTML. It can be used to target this item through css or for displaying this item.','TEXT',TRUE,FALSE), diff --git a/examples/official-site/sqlpage/migrations/76_toast.sql b/examples/official-site/sqlpage/migrations/76_toast.sql index 38393dcc..4afc43fb 100644 --- a/examples/official-site/sqlpage/migrations/76_toast.sql +++ b/examples/official-site/sqlpage/migrations/76_toast.sql @@ -13,9 +13,8 @@ INSERT INTO parameter(component, name, description, type, top_level, optional) S ('dismissible', 'Whether to render an accessible manual close button. Defaults to true and is independent of automatic dismissal.', 'BOOLEAN', TRUE, TRUE), ('duration', 'Automatic dismissal delay in milliseconds. Defaults to 5000. Set to 0 to keep the toast visible until manually dismissed (when `dismissible` is true) or the page is left.', 'INTEGER', TRUE, TRUE), ('position', 'Screen placement: `top-start`, `top-center`, `top-end`, `bottom-start`, `bottom-center`, or `bottom-end`. Defaults to `top-end`; invalid values safely fall back to that default.', 'TEXT', TRUE, TRUE), - ('trigger', 'Optional URL fragment that opens the toast without reloading the page, with or without the leading `#`. When set, the toast does not open on page load and can be opened repeatedly by a link or button whose target is that fragment. Multiple toasts can share a trigger to open as a stack.', 'TEXT', TRUE, TRUE), - ('id', 'Optional stable HTML ID for the toast.', 'TEXT', TRUE, TRUE), - ('class', 'Optional custom CSS class appended to the toast.', 'TEXT', TRUE, TRUE) + ('trigger', 'Optional URL fragment that opens the toast without reloading the page, with or without the leading `#`. When set, the toast does not open on page load and can be opened repeatedly by a link or button whose target is that fragment. Multiple toasts can share a trigger to open as a stack.', 'TEXT', TRUE, TRUE) + -- id and class come from 99_shared_id_class_attributes.sql ) x; INSERT INTO example(component, description, properties) VALUES diff --git a/examples/official-site/sqlpage/migrations/99_shared_id_class_attributes.sql b/examples/official-site/sqlpage/migrations/99_shared_id_class_attributes.sql index c4f779b6..6c2a9bf1 100644 --- a/examples/official-site/sqlpage/migrations/99_shared_id_class_attributes.sql +++ b/examples/official-site/sqlpage/migrations/99_shared_id_class_attributes.sql @@ -1,22 +1,40 @@ -INSERT INTO parameter(component, top_level, name, description, type, optional) +-- 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. + +INSERT INTO parameter(component, top_level, name, description, type, optional) SELECT *, 'id', 'id attribute added to the container in HTML. It can be used to target this item through css or for scrolling to this item through links (use "#id" in link url).', 'TEXT', TRUE FROM (VALUES ('alert', TRUE), + ('big_number', TRUE), + ('big_number', FALSE), ('breadcrumb', TRUE), + ('card', FALSE), ('chart', TRUE), ('code', TRUE), ('csv', TRUE), ('datagrid', TRUE), ('datagrid', FALSE), + ('empty_state', TRUE), ('hero', TRUE), ('list', TRUE), ('list', FALSE), ('map', TRUE), + ('tab', TRUE), ('tab', FALSE), ('table', TRUE), ('timeline', TRUE), ('timeline', FALSE), ('title', TRUE), + ('toast', TRUE), ('tracking', TRUE), ('text', TRUE), ('carousel', TRUE), @@ -34,23 +52,29 @@ INSERT INTO parameter(component, top_level, name, description, type, optional) SELECT *, 'class', 'class attribute added to the container in HTML. It can be used to apply custom styling to this item through css. Added in v0.18.0.', 'TEXT', TRUE FROM (VALUES ('alert', TRUE), + ('big_number', TRUE), + ('big_number', FALSE), ('breadcrumb', TRUE), ('button', TRUE), + ('card', TRUE), ('card', FALSE), ('chart', TRUE), ('code', TRUE), ('csv', TRUE), ('datagrid', TRUE), ('divider', TRUE), + ('empty_state', TRUE), ('form', TRUE), ('list', TRUE), ('list', FALSE), ('map', TRUE), + ('tab', TRUE), ('tab', FALSE), ('table', TRUE), ('timeline', TRUE), ('timeline', FALSE), ('title', TRUE), + ('toast', TRUE), ('tracking', TRUE), ('carousel', TRUE), ('login', TRUE), diff --git a/sqlpage/templates/table.handlebars b/sqlpage/templates/table.handlebars index e20b084b..a40c6b1e 100644 --- a/sqlpage/templates/table.handlebars +++ b/sqlpage/templates/table.handlebars @@ -3,7 +3,7 @@ {{#if (or search initial_search_value)}}
; row: Set }; + +/** + * The context a Handlebars expression is evaluated in. `top` is the first row + * of the result set, `row` is one of the following rows, and `nested` is an + * object reached through `{{#each}}` or `{{#with}}` — the sub-properties of a + * json property, which are documented in the parent property's description + * rather than as rows of their own. + */ +type Context = "top" | "row" | "nested"; + +function properties_of_template(source: string): TemplateProperties { + const top = new Set(); + const row = new Set(); + const contexts: Context[] = ["top"]; + + for (const [, raw_body] of source.matchAll(/\{\{([^}]*)\}\}/g)) { + let body = raw_body + .replace(/^[{~]+/, "") + .replace(/[~}]+$/, "") + .trim(); + if (body.startsWith("!")) continue; // comment + + if (/^#each_row\b/.test(body)) { + contexts.push("row"); + continue; + } + if (/^\/each_row\b/.test(body)) { + contexts.pop(); + continue; + } + + const is_closing = body.startsWith("/"); + const opens_a_nested_context = /^#(each|with)\b/.test(body); + body = body.replace(/^[#^/>&]+/, "").trim(); + if (is_closing) { + if (/^(each|with)\b/.test(body)) contexts.pop(); + continue; + } + + // `{{else if (...)}}` chains an inner `if`, which is not a property. + body = body.replace(/^else\s+/, ""); + // String literals may contain anything, including what looks like a path. + body = body.replace(/"[^"]*"/g, " ").replace(/'[^']*'/g, " "); + // Block parameters (`{{#each x as |y|}}`) name the inner context. + const block_params = body.indexOf(" as |"); + if (block_params >= 0) body = body.slice(0, block_params); + + // A bare name is a helper call when it is the first token of the mustache + // or of a subexpression, and a property reference anywhere else. + let is_callee = true; + for (const token of body.split(/(\s+|\(|\))/)) { + if (!token.trim()) continue; + if (token === "(") { + is_callee = true; + continue; + } + if (token === ")") { + is_callee = false; + continue; + } + const in_callee_position = is_callee; + is_callee = false; + + let name = token; + if (/^[0-9]/.test(name)) continue; // numeric literal + if (name.includes("=")) name = name.slice(name.indexOf("=") + 1); // hash argument + let parents = 0; + while (name.startsWith("../")) { + parents += 1; + name = name.slice(3); + } + if (name.startsWith("@") || name.startsWith(".") || name.startsWith("|")) + continue; + if (name.startsWith("this.")) name = name.slice(5); + if (name === "this" || name === "") continue; + name = name.split(/[.[]/)[0]; // `a.b` and `a.[0]` are reads of `a` + if (!/^[A-Za-z_][A-Za-z_0-9]*$/.test(name)) continue; + if (LITERALS.has(name)) continue; + if (parents === 0 && in_callee_position && HELPERS.has(name)) continue; + + const context = contexts[Math.max(0, contexts.length - 1 - parents)]; + if (context === "top") top.add(name); + else if (context === "row") row.add(name); + } + + if (opens_a_nested_context) contexts.push("nested"); + } + + return { top, row }; +} + +function read_templates(): Map { + const templates = new Map(); + for (const file of fs.readdirSync(TEMPLATES_DIR)) { + if (!file.endsWith(".handlebars")) continue; + const name = file.slice(0, -".handlebars".length); + if (TEMPLATES_WITHOUT_DOCUMENTATION.has(name)) continue; + const source = fs.readFileSync(path.join(TEMPLATES_DIR, file), "utf8"); + templates.set(name, properties_of_template(source)); + } + return templates; +} + +function read_documentation(): Map { + const migrations = fs + .readdirSync(MIGRATIONS_DIR) + .filter((file) => file.endsWith(".sql")) + // SQLPage applies migrations in the order of their numeric prefix. + .sort( + (a, b) => + Number.parseInt(a, 10) - Number.parseInt(b, 10) || a.localeCompare(b), + ); + + const db = new DatabaseSync(":memory:"); + for (const file of migrations) { + db.exec(fs.readFileSync(path.join(MIGRATIONS_DIR, file), "utf8")); + } + + const documented = new Map(); + const rows = db + .prepare("select component, name, top_level from parameter") + .all() as { component: string; name: string; top_level: number }[]; + for (const { component, name, top_level } of rows) { + let entry = documented.get(component); + if (!entry) { + entry = { top: new Set(), row: new Set() }; + documented.set(component, entry); + } + (top_level ? entry.top : entry.row).add(name); + } + db.close(); + return documented; +} + +const templates = read_templates(); +const documented = read_documentation(); + +test("every component documented by the official site has a template", () => { + const missing = [...documented.keys()].filter( + (component) => + !templates.has(component) && + !COMPONENTS_WITHOUT_A_TEMPLATE.has(component), + ); + assert.deepEqual( + missing, + [], + `These components are documented but have no sqlpage/templates/*.handlebars file. ` + + `If they are rendered by src/render.rs, add them to COMPONENTS_WITHOUT_A_TEMPLATE.`, + ); +}); + +test("every property read by a template is documented", () => { + const undocumented: string[] = []; + for (const [component, properties] of templates) { + const docs = documented.get(component) ?? { + top: new Set(), + row: new Set(), + }; + for (const level of ["top", "row"] satisfies Level[]) { + for (const name of properties[level]) { + if (!docs[level].has(name)) + undocumented.push(`${component}.${name} (${level}-level)`); + } + } + } + assert.deepEqual( + undocumented.sort(), + [], + `These properties are read by a template but not documented. Add a row to ` + + `the component's migration in examples/official-site/sqlpage/migrations/.`, + ); +}); + +test("every documented property is read by its template", () => { + const unimplemented: string[] = []; + for (const [component, docs] of documented) { + const properties = templates.get(component); + if (!properties) continue; // rendered by src/, checked by the test above + for (const level of ["top", "row"] satisfies Level[]) { + for (const name of docs[level]) { + if (properties[level].has(name)) continue; + if (DOCUMENTED_WITHOUT_A_TEMPLATE_REFERENCE.has(`${component}.${name}`)) + continue; + const other_level = level === "top" ? "row" : "top"; + unimplemented.push( + properties[other_level].has(name) + ? `${component}.${name} is documented as ${level}-level but the template reads it at the ${other_level} level` + : `${component}.${name} (${level}-level) is documented but no template reads it`, + ); + } + } + } + assert.deepEqual( + unimplemented.sort(), + [], + `Remove the documentation, or fix its top_level, in ` + + `examples/official-site/sqlpage/migrations/.`, + ); +});