Components #522

allisonhorst · 2024-01-12T16:23:56Z

Will eventually include docs for:

Components overview page (Components overview page #492 in progress, needs final updates after other component pages done)
Inputs - overview page + view (merged in Inputs overview #516)
Inputs - individual pages (merged in Inputs pages #540)
Themes preview page (Cindy in progress, w/ Jeff & Ramona)
~~Dash.bignumber docs~~
resize docs (Trebor drafted in add resize doc #553 , Mike has also added documentation in std lib Dash.resize → resize #555 )
card docs (Allison PR Cards #561)
grid docs (Trebor PR add grid class documentation #559)
Chart snippets (added in Charts directory in this this PR to start, see update in Adds Grouping data (with hexbin, histogram) in Charts #560 )

Also TODO:

Move static files (e.g. horse.jpg) to docs/data
Ensure cut components are removed (pages and sidebar items, e.g. annotation, bignumber)

* update button.md * update markdown text section

* first draft inputs overview * updates nav with javascript/inputs * Apply suggestions from Fil review Co-authored-by: Philippe Rivière <[email protected]> * updates to use olympians, uses lowercase and 'inputs' throughout * case fixes and minor update Co-authored-by: Philippe Rivière <[email protected]> --------- Co-authored-by: Allison Horst <[email protected]> Co-authored-by: Philippe Rivière <[email protected]>

Fil · 2024-01-12T16:35:24Z

remove the athletes.csv and penguins.csv files
lowercase the Inputs
the File input is now fully working
"check if pointing to d3-group notebook is best" => no, prefer https://d3js.org/d3-array/group

* change todos to comments and add Inputs.search doc * add API reference

Co-authored-by: Allison Horst <[email protected]>

mbostock · 2024-01-15T17:10:18Z

docs/javascript/inputs.md

This should start with a generic description of what “inputs” are within the concept of the Observable CLI before introducing “Observable Inputs” as a specific solution. It should mention the concepts (and link to) the concepts of reactive top-level variables, generators, and the display function, and then first introduce the view function as how inputs are declared. We should also mention that Generators.input is used under the hood, and link to that too (see Observable Generators).

Only after these concepts are introduced should be introduce Observable Inputs as a library (an implementation) of commonly-needed input components, each of which is a function that returns an HTML element that emits input events (for compatibility with view and Generators.input).

So, yes, the first code snippet of actual usage should be view + Inputs.whatever, so that people see what the recommended usage pattern is. But the text needs to explain what’s happening so that people have a conceptual understanding of how it works.

Updates here: #545 (merged into Components branch, top-level Inputs page)

mbostock · 2024-01-15T17:13:26Z

docs/inputs/us-state-capitals.tsv

This is already available in docs/lib and we shouldn’t duplicate it. We could move (static) data files to docs/data, but that’ll mean a few more relative paths in the examples. Maybe that’s fine… and it would be consistent with what we now recommend.

We could move (static) data files to docs/data, but that’ll mean a few more relative paths in the examples. Maybe that’s fine… and it would be consistent with what we now recommend.

I think we should do this.

mbostock · 2024-01-15T17:15:07Z

docs/charts/histogram.md

To align with Plot’s mental model, perhaps better to combine this and the hexbin example into a bin.md that demonstrates group, bin, and hexbin transforms?

I like this.

I am stuck on naming. The existing sidebar items and page titles are general chart types (e.g. "Line", "Area" for nav, "Line charts", "Area charts" for page title).

Here, that could be something like:

Sidebar: "Aggregation", "Summary"

Page title: "Summary charts", "Aggregated data", "Aggregated charts", "Charts with aggregated/binned/grouped data" (?)

Recommendations for naming this section (in the sidebar, and page title) are appreciated.

my suggestion: "Grouping data"

Will add "Grouping data" page with histogram, hexbin.

Updated in #560

* update inputs-overview intro text * links * remove h2 for intro * adds Inputs general intro, update view documentation in Display page * Update view summary in javascript/display Co-authored-by: Philippe Rivière <[email protected]> * Apply suggestions from code review Co-authored-by: Philippe Rivière <[email protected]> --------- Co-authored-by: Allison Horst <[email protected]> Co-authored-by: Philippe Rivière <[email protected]>

Adds `card` class --------- Co-authored-by: Allison Horst <[email protected]> Co-authored-by: Robert Harris <[email protected]> Co-authored-by: Cindy <[email protected]> Co-authored-by: Philippe Rivière <[email protected]>

mbostock · 2024-01-18T16:02:51Z

observablehq.config.ts

@@ -15,10 +16,58 @@ export default {
        {name: "Imports", path: "/javascript/imports"},
        {name: "Files", path: "/javascript/files"},
        {name: "Promises", path: "/javascript/promises"},
+        {name: "Inputs", path: "/javascript/inputs"},


Let’s move this to after Display. (I don’t want to interrupt Promises and Generators, which are closely related in terms of implicit resolution of values across code blocks, and Inputs are closely related to Display.)

Adds brief overview of components (layout, charts, inputs) --------- Co-authored-by: Allison Horst <[email protected]> Co-authored-by: Philippe Rivière <[email protected]>

* add Grouping data section with hexbin, histogram * adds Grouping data page to sidebar in Charts * minor fixes and update hexbin chart to use dot mark * Apply suggestions from code review Co-authored-by: Philippe Rivière <[email protected]> --------- Co-authored-by: Allison Horst <[email protected]> Co-authored-by: Philippe Rivière <[email protected]>

… components

* add grid doc * change how example code is rendered * remove word salid * improve advice * fix capitolization * Update docs/layout/grid.md Co-authored-by: Philippe Rivière <[email protected]> * Update docs/layout/grid.md Co-authored-by: Philippe Rivière <[email protected]> * Update docs/layout/grid.md Co-authored-by: Philippe Rivière <[email protected]> * Update docs/layout/grid.md Co-authored-by: Philippe Rivière <[email protected]> * remove overshare --------- Co-authored-by: Philippe Rivière <[email protected]>

* add resize doc * fix some typos * fix formatting * add both cases

allisonhorst · 2024-01-18T19:46:58Z

Things I noticed during quick overall review, but did not update:

The 4x4 grid in layout/cards.md looks bad (spacing, not resizing)
Do we want consistent title conventions across sections? JavaScript section uses "JavaScript: Generators" convention, but in Inputs section we use "Button input" and in Charts we use "Area chart". Do we want update to "Inputs: Button", "Charts: Area" and similar throughout for naming consistency?
The link for formatLocaleAuto in Inputs API (https://github.com/observablehq/inputs?tab=readme-ov-file#formatLocaleAuto) doesn't take you anywhere on page (see in checkbox options). I updated to https://github.com/observablehq/inputs?tab=readme-ov-file#inputsformatlocaleautolocale. Is that correct?
The slug to view documentation (in javascript/inputs.md) has parentheses (#view(element)) which probably needs updating
Didn't move Top 10 bar chart, Weighted sum bar chart, or moving average line chart to the "Grouping data" page with hexbin & histogram, but it might make good sense to move them there since they use group/window transforms.
The "Grouping data" in the sidebar nav makes my eye twitch a bit alongside all the other single word Chart items

cinxmo · 2024-01-18T21:18:38Z

docs/components.md

+Observable Markdown offers a number of [built-in themes](./config#theme) that you can compose to create, say, wide pages with an alternative dark color theme:
+
+```js run=false
+theme: ["dark-alt", "wide"]


is dark-alt an official theme? or should it be ["dark", "alt", "wide"]?

Updating to ["dark", "alt", "wide"] thanks!

cinxmo · 2024-01-18T21:20:54Z

docs/components.md

+
+```yaml
+---
+theme: ["dark-alt", "wide"]


nit: I think both [dark-alt, wide] (without quotes) and ["dark-alt", "wide"] works. could we standardize between https://cli.observablehq.com/config#theme and here? also I see the pattern of having the description and then the code block:

The code below, when included in the [config file](./config), specifies the default theme for the project: ```js run=false theme: ["dark-alt", "wide"] ``` In addition, you can specify the theme for a single page in its [front matter](markdown#front-matter): ```yaml --- theme: ["dark-alt", "wide"] --- ```

Updating to match pattern in config (quotes in config file, no quotes in frontmatter)

docs/components.md

cinxmo · 2024-01-18T21:51:30Z

docs/components.md

+Resize exists in the Observable standard library, or can be imported explicitly:
+
+```js
+import {resize} from "npm:@observablehq/stdlib";


nit: should we add this to show the explicit import?

import {resize} from "npm:@observablehq/stdlib";

Yes, added echo

cinxmo · 2024-01-18T21:56:19Z

docs/components.md

+const pickSpecies = view(Inputs.radio(["Adelie", "Chinstrap", "Gentoo"], {value: "Gentoo", label: "Penguin species:"}))
+```
+
+The value of `pickSpecies` (<tt>="${pickSpecies}"</tt>) can then be accessed elsewhere in the page, as a parameter in other computations, and to create interactive charts, tables or text with [inline expressions](./javascript#inline-expressions).


nit: seems like <tt> has been deprecated

good catch, it should be <var>

docs/inputs/button.md

Co-authored-by: Cindy <[email protected]>

Allison Horst and others added 14 commits January 8, 2024 18:06

draft nav structure

44d850b

adds blank files

c07e4ca

starts migrating Inputs notebooks

0c86e4e

adds data files

2b1ed96

testing modified

995615c

migrates text area, toggle inputs, plus minor text changes

0d00209

Rearrange nav items, update Inputs H1

126a449

start migrating Plot snippets from Add Cell menu

78e3958

adds Plot snippets to Charts

e2dbd67

update cell chart text

e3b367f

update button.md documentation (#472)

2df7d1a

* update button.md * update markdown text section

Merge branch 'main' into components

bdd5704

Merge branch 'main' into components

e0af0b7

allisonhorst requested a review from Fil January 12, 2024 16:23

allisonhorst marked this pull request as draft January 12, 2024 16:24

cinxmo and others added 4 commits January 12, 2024 12:24

Mark TODOs as comments and add Inputs.search documentation (#518)

f7ab5e5

* change todos to comments and add Inputs.search doc * add API reference

Merge branch 'main' into components

e890def

Merge branch 'main' into components

54a696f

updates Inputs individual pages (#540)

2fe2fbc

Co-authored-by: Allison Horst <[email protected]>

mbostock reviewed Jan 15, 2024

View reviewed changes

Allison Horst and others added 6 commits January 15, 2024 11:51

Merge branch 'main' into components

e22c801

Merge branch 'main' into components

5bc4180

Merge branch 'main' into components

ce207b8

Merge branch 'components' of github.com:observablehq/cli into components

4ada27f

remove components pages no longer used

c3d82e8

Allison Horst and others added 2 commits January 17, 2024 17:19

Merge branch 'main' into components

a5b11f8

Cards (#561)

4fa1abc

Adds `card` class --------- Co-authored-by: Allison Horst <[email protected]> Co-authored-by: Robert Harris <[email protected]> Co-authored-by: Cindy <[email protected]> Co-authored-by: Philippe Rivière <[email protected]>

mbostock reviewed Jan 18, 2024

View reviewed changes

allisonhorst and others added 8 commits January 18, 2024 09:12

Components overview page (#492)

26423f1

Adds brief overview of components (layout, charts, inputs) --------- Co-authored-by: Allison Horst <[email protected]> Co-authored-by: Philippe Rivière <[email protected]>

Merge branch 'main' into components

1256daa

Merge branch 'components' of https://github.com/observablehq/cli into…

3b6e75b

… components

add resize doc (#553)

9f10e32

* add resize doc * fix some typos * fix formatting * add both cases

minor fixes, link updates

5737ea7

Merge branch 'main' into components

1491428

allisonhorst marked this pull request as ready for review January 18, 2024 19:28

allisonhorst requested review from trebor and cinxmo January 18, 2024 19:31

cinxmo reviewed Jan 18, 2024

View reviewed changes

docs/components.md Outdated Show resolved Hide resolved

cinxmo reviewed Jan 18, 2024

View reviewed changes

docs/components.md Outdated Show resolved Hide resolved

cinxmo reviewed Jan 18, 2024

View reviewed changes

docs/inputs/button.md Outdated Show resolved Hide resolved

allisonhorst and others added 5 commits January 18, 2024 15:18

Capitalize markdown

835fd80

Co-authored-by: Cindy <[email protected]>

code alignment fixes

c8877fb

Co-authored-by: Cindy <[email protected]>

echo explicit resize import

6319f91

Merge branch 'components' of github.com:observablehq/cli into components

ec01aab

updates theme combo, matches pattern in config for theme examples

6be8ca0

cinxmo approved these changes Jan 18, 2024

View reviewed changes

allisonhorst merged commit da9afa8 into main Jan 18, 2024

allisonhorst deleted the components branch January 18, 2024 23:08

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Components #522

Components #522

allisonhorst commented Jan 12, 2024 •

edited

Loading

Fil commented Jan 12, 2024

mbostock Jan 15, 2024 •

edited

Loading

allisonhorst Jan 18, 2024

mbostock Jan 15, 2024

allisonhorst Jan 15, 2024

mbostock Jan 15, 2024

allisonhorst Jan 15, 2024

Fil Jan 15, 2024

allisonhorst Jan 17, 2024

allisonhorst Jan 18, 2024

mbostock Jan 18, 2024

allisonhorst commented Jan 18, 2024

cinxmo Jan 18, 2024

allisonhorst Jan 18, 2024

cinxmo Jan 18, 2024 •

edited

Loading

allisonhorst Jan 18, 2024

cinxmo Jan 18, 2024

allisonhorst Jan 18, 2024

cinxmo Jan 18, 2024

Fil Jan 18, 2024

Components #522

Components #522

Conversation

allisonhorst commented Jan 12, 2024 • edited Loading

Fil commented Jan 12, 2024

mbostock Jan 15, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

allisonhorst commented Jan 18, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cinxmo Jan 18, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

allisonhorst commented Jan 12, 2024 •

edited

Loading

mbostock Jan 15, 2024 •

edited

Loading

cinxmo Jan 18, 2024 •

edited

Loading