This is an automated email from the ASF dual-hosted git repository. rusackas pushed a commit to branch developer_portal in repository https://gitbox.apache.org/repos/asf/superset.git
commit 7519aabc7b04f4cda8dc077b42babe9078f82ac4 Author: Evan Rusackas <e...@rusackas.com> AuthorDate: Mon Mar 31 23:43:03 2025 -0600 versioning POC --- docs/components/versions.json | 3 +- .../version-1.0.0/chart-components/bar-chart.md | 87 ++++++++++++++++++++ .../version-1.0.0/index.md | 41 ++++++++++ .../version-1.0.0/introduction.md | 41 ++++++++++ .../version-1.0.0/layout-components/grid.md | 95 ++++++++++++++++++++++ .../version-1.0.0/ui-components/button.md | 60 ++++++++++++++ .../version-1.0.0/chart-components/bar-chart.md | 87 ++++++++++++++++++++ .../versioned_docs/version-1.0.0/index.md | 43 ++++++++++ .../versioned_docs/version-1.0.0/introduction.md | 43 ++++++++++ .../version-1.0.0/layout-components/grid.md | 95 ++++++++++++++++++++++ .../version-1.0.0/ui-components/button.md | 60 ++++++++++++++ .../version-1.0.0/versions.json | 3 + .../version-1.0.0-sidebars.json | 39 +++++++++ docs/components_versions.json | 3 + 14 files changed, 698 insertions(+), 2 deletions(-) diff --git a/docs/components/versions.json b/docs/components/versions.json index 6d8eb78d16..5e1abcd8a6 100644 --- a/docs/components/versions.json +++ b/docs/components/versions.json @@ -1,4 +1,3 @@ [ - "1.0.0", - "current" + "1.0.0" ] diff --git a/docs/components_versioned_docs/version-1.0.0/chart-components/bar-chart.md b/docs/components_versioned_docs/version-1.0.0/chart-components/bar-chart.md new file mode 100644 index 0000000000..a9dc7cb3bc --- /dev/null +++ b/docs/components_versioned_docs/version-1.0.0/chart-components/bar-chart.md @@ -0,0 +1,87 @@ +--- +title: Bar Chart +sidebar_position: 1 +--- + +# Bar Chart Component + +The Bar Chart component is used to visualize categorical data with rectangular bars. + +## Props + +| Prop | Type | Default | Description | +|------|------|---------|-------------| +| `data` | `array` | `[]` | Array of data objects to visualize | +| `width` | `number` | `800` | Width of the chart in pixels | +| `height` | `number` | `600` | Height of the chart in pixels | +| `xField` | `string` | - | Field name for x-axis values | +| `yField` | `string` | - | Field name for y-axis values | +| `colorField` | `string` | - | Field name for color encoding | +| `colorScheme` | `string` | `'supersetColors'` | Color scheme to use | +| `showLegend` | `boolean` | `true` | Whether to show the legend | +| `showGrid` | `boolean` | `true` | Whether to show grid lines | +| `labelPosition` | `string` | `'top'` | Position of bar labels: 'top', 'middle', 'bottom' | + +## Examples + +### Basic Bar Chart + +```jsx +import { BarChart } from '@superset-ui/chart-components'; + +const data = [ + { category: 'A', value: 10 }, + { category: 'B', value: 20 }, + { category: 'C', value: 15 }, + { category: 'D', value: 25 }, +]; + +function Example() { + return ( + <BarChart + data={data} + width={800} + height={400} + xField="category" + yField="value" + colorScheme="supersetColors" + /> + ); +} +``` + +### Grouped Bar Chart + +```jsx +import { BarChart } from '@superset-ui/chart-components'; + +const data = [ + { category: 'A', group: 'Group 1', value: 10 }, + { category: 'A', group: 'Group 2', value: 15 }, + { category: 'B', group: 'Group 1', value: 20 }, + { category: 'B', group: 'Group 2', value: 25 }, + { category: 'C', group: 'Group 1', value: 15 }, + { category: 'C', group: 'Group 2', value: 10 }, +]; + +function Example() { + return ( + <BarChart + data={data} + width={800} + height={400} + xField="category" + yField="value" + colorField="group" + colorScheme="supersetColors" + /> + ); +} +``` + +## Best Practices + +- Use bar charts when comparing quantities across categories +- Sort bars by value for better readability, unless there's a natural order to the categories +- Use consistent colors for the same categories across different charts +- Consider using horizontal bar charts when category labels are long diff --git a/docs/components_versioned_docs/version-1.0.0/index.md b/docs/components_versioned_docs/version-1.0.0/index.md new file mode 100644 index 0000000000..affdf24f61 --- /dev/null +++ b/docs/components_versioned_docs/version-1.0.0/index.md @@ -0,0 +1,41 @@ +--- +title: Component Library +sidebar_position: 1 +--- + +# Superset Component Library + +Welcome to the Apache Superset Component Library documentation. This section provides comprehensive documentation for all the UI components, chart components, and layout components used in Superset. + +## What is the Component Library? + +The Component Library is a collection of reusable UI components that are used to build the Superset user interface. These components are designed to be consistent, accessible, and easy to use. + +## Component Categories + +The Component Library is organized into the following categories: + +### UI Components + +Basic UI components like buttons, inputs, dropdowns, and other form elements. + +### Chart Components + +Visualization components used to render different types of charts and graphs. + +### Layout Components + +Components used for page layout, such as containers, grids, and navigation elements. + +## Versioning + +The Component Library documentation follows its own versioning scheme, independent from the main Superset documentation. This allows us to update the component documentation as the components evolve, without affecting the main documentation. + +## Getting Started + +Browse the sidebar to explore the different components available in the library. Each component documentation includes: + +- Component description and purpose +- Props and configuration options +- Usage examples +- Best practices diff --git a/docs/components_versioned_docs/version-1.0.0/introduction.md b/docs/components_versioned_docs/version-1.0.0/introduction.md new file mode 100644 index 0000000000..affdf24f61 --- /dev/null +++ b/docs/components_versioned_docs/version-1.0.0/introduction.md @@ -0,0 +1,41 @@ +--- +title: Component Library +sidebar_position: 1 +--- + +# Superset Component Library + +Welcome to the Apache Superset Component Library documentation. This section provides comprehensive documentation for all the UI components, chart components, and layout components used in Superset. + +## What is the Component Library? + +The Component Library is a collection of reusable UI components that are used to build the Superset user interface. These components are designed to be consistent, accessible, and easy to use. + +## Component Categories + +The Component Library is organized into the following categories: + +### UI Components + +Basic UI components like buttons, inputs, dropdowns, and other form elements. + +### Chart Components + +Visualization components used to render different types of charts and graphs. + +### Layout Components + +Components used for page layout, such as containers, grids, and navigation elements. + +## Versioning + +The Component Library documentation follows its own versioning scheme, independent from the main Superset documentation. This allows us to update the component documentation as the components evolve, without affecting the main documentation. + +## Getting Started + +Browse the sidebar to explore the different components available in the library. Each component documentation includes: + +- Component description and purpose +- Props and configuration options +- Usage examples +- Best practices diff --git a/docs/components_versioned_docs/version-1.0.0/layout-components/grid.md b/docs/components_versioned_docs/version-1.0.0/layout-components/grid.md new file mode 100644 index 0000000000..f0e7a99b52 --- /dev/null +++ b/docs/components_versioned_docs/version-1.0.0/layout-components/grid.md @@ -0,0 +1,95 @@ +--- +title: Grid +sidebar_position: 1 +--- + +# Grid Component + +The Grid component provides a flexible layout system for arranging content in rows and columns. + +## Props + +| Prop | Type | Default | Description | +|------|------|---------|-------------| +| `gutter` | `number` or `[number, number]` | `0` | Grid spacing between items, can be a single number or [horizontal, vertical] | +| `columns` | `number` | `12` | Number of columns in the grid | +| `justify` | `string` | `'start'` | Horizontal alignment: 'start', 'center', 'end', 'space-between', 'space-around' | +| `align` | `string` | `'top'` | Vertical alignment: 'top', 'middle', 'bottom' | +| `wrap` | `boolean` | `true` | Whether to wrap items when they overflow | + +### Row Props + +| Prop | Type | Default | Description | +|------|------|---------|-------------| +| `gutter` | `number` or `[number, number]` | `0` | Spacing between items in the row | +| `justify` | `string` | `'start'` | Horizontal alignment for this row | +| `align` | `string` | `'top'` | Vertical alignment for this row | + +### Col Props + +| Prop | Type | Default | Description | +|------|------|---------|-------------| +| `span` | `number` | - | Number of columns the grid item spans | +| `offset` | `number` | `0` | Number of columns the grid item is offset | +| `xs`, `sm`, `md`, `lg`, `xl` | `number` or `object` | - | Responsive props for different screen sizes | + +## Examples + +### Basic Grid + +```jsx +import { Grid, Row, Col } from '@superset-ui/core'; + +function Example() { + return ( + <Grid> + <Row gutter={16}> + <Col span={8}> + <div>Column 1</div> + </Col> + <Col span={8}> + <div>Column 2</div> + </Col> + <Col span={8}> + <div>Column 3</div> + </Col> + </Row> + </Grid> + ); +} +``` + +### Responsive Grid + +```jsx +import { Grid, Row, Col } from '@superset-ui/core'; + +function Example() { + return ( + <Grid> + <Row gutter={[16, 24]}> + <Col xs={24} sm={12} md={8} lg={6}> + <div>Responsive Column 1</div> + </Col> + <Col xs={24} sm={12} md={8} lg={6}> + <div>Responsive Column 2</div> + </Col> + <Col xs={24} sm={12} md={8} lg={6}> + <div>Responsive Column 3</div> + </Col> + <Col xs={24} sm={12} md={8} lg={6}> + <div>Responsive Column 4</div> + </Col> + </Row> + </Grid> + ); +} +``` + +## Best Practices + +- Use the Grid system for complex layouts that need to be responsive +- Specify column widths for different screen sizes to ensure proper responsive behavior +- Use gutters to create appropriate spacing between grid items +- Keep the grid structure consistent throughout your application +- Consider using the grid system for dashboard layouts to ensure consistent spacing and alignment diff --git a/docs/components_versioned_docs/version-1.0.0/ui-components/button.md b/docs/components_versioned_docs/version-1.0.0/ui-components/button.md new file mode 100644 index 0000000000..51690d1080 --- /dev/null +++ b/docs/components_versioned_docs/version-1.0.0/ui-components/button.md @@ -0,0 +1,60 @@ +--- +title: Button +sidebar_position: 1 +--- + +# Button Component + +The Button component is a fundamental UI element used throughout Superset for user interactions. + +## Props + +| Prop | Type | Default | Description | +|------|------|---------|-------------| +| `buttonStyle` | `string` | `'primary'` | Button style: 'primary', 'secondary', 'link', 'dashed', 'danger' | +| `buttonSize` | `string` | `'default'` | Button size: 'small', 'default', 'large' | +| `disabled` | `boolean` | `false` | Whether the button is disabled | +| `onClick` | `function` | - | Callback when button is clicked | +| `href` | `string` | - | Turns button into an anchor link | +| `target` | `string` | - | Target attribute for anchor links | + +## Examples + +### Basic Button + +```jsx +import { Button } from '@superset-ui/core'; + +function Example() { + return ( + <Button buttonStyle="primary" onClick={() => console.log('Clicked!')}> + Click Me + </Button> + ); +} +``` + +### Button Styles + +```jsx +import { Button } from '@superset-ui/core'; + +function Example() { + return ( + <> + <Button buttonStyle="primary">Primary</Button> + <Button buttonStyle="secondary">Secondary</Button> + <Button buttonStyle="link">Link</Button> + <Button buttonStyle="dashed">Dashed</Button> + <Button buttonStyle="danger">Danger</Button> + </> + ); +} +``` + +## Best Practices + +- Use primary buttons for the main action in a form or page +- Use secondary buttons for alternative actions +- Limit the number of primary buttons on a page to avoid confusion +- Use consistent button styles throughout your application diff --git a/docs/components_versioned_docs/version-1.0.0/versioned_docs/version-1.0.0/chart-components/bar-chart.md b/docs/components_versioned_docs/version-1.0.0/versioned_docs/version-1.0.0/chart-components/bar-chart.md new file mode 100644 index 0000000000..5bed3a5d92 --- /dev/null +++ b/docs/components_versioned_docs/version-1.0.0/versioned_docs/version-1.0.0/chart-components/bar-chart.md @@ -0,0 +1,87 @@ +--- +title: Bar Chart (v1.0.0) +sidebar_position: 1 +--- + +# Bar Chart Component + +The Bar Chart component is used to visualize categorical data with rectangular bars. + +## Props + +| Prop | Type | Default | Description | +|------|------|---------|-------------| +| `data` | `array` | `[]` | Array of data objects to visualize | +| `width` | `number` | `800` | Width of the chart in pixels | +| `height` | `number` | `600` | Height of the chart in pixels | +| `xField` | `string` | - | Field name for x-axis values | +| `yField` | `string` | - | Field name for y-axis values | +| `colorField` | `string` | - | Field name for color encoding | +| `colorScheme` | `string` | `'supersetColors'` | Color scheme to use | +| `showLegend` | `boolean` | `true` | Whether to show the legend | +| `showGrid` | `boolean` | `true` | Whether to show grid lines | +| `labelPosition` | `string` | `'top'` | Position of bar labels: 'top', 'middle', 'bottom' | + +## Examples + +### Basic Bar Chart + +```jsx +import { BarChart } from '@superset-ui/chart-components'; + +const data = [ + { category: 'A', value: 10 }, + { category: 'B', value: 20 }, + { category: 'C', value: 15 }, + { category: 'D', value: 25 }, +]; + +function Example() { + return ( + <BarChart + data={data} + width={800} + height={400} + xField="category" + yField="value" + colorScheme="supersetColors" + /> + ); +} +``` + +### Grouped Bar Chart + +```jsx +import { BarChart } from '@superset-ui/chart-components'; + +const data = [ + { category: 'A', group: 'Group 1', value: 10 }, + { category: 'A', group: 'Group 2', value: 15 }, + { category: 'B', group: 'Group 1', value: 20 }, + { category: 'B', group: 'Group 2', value: 25 }, + { category: 'C', group: 'Group 1', value: 15 }, + { category: 'C', group: 'Group 2', value: 10 }, +]; + +function Example() { + return ( + <BarChart + data={data} + width={800} + height={400} + xField="category" + yField="value" + colorField="group" + colorScheme="supersetColors" + /> + ); +} +``` + +## Best Practices + +- Use bar charts when comparing quantities across categories +- Sort bars by value for better readability, unless there's a natural order to the categories +- Use consistent colors for the same categories across different charts +- Consider using horizontal bar charts when category labels are long diff --git a/docs/components_versioned_docs/version-1.0.0/versioned_docs/version-1.0.0/index.md b/docs/components_versioned_docs/version-1.0.0/versioned_docs/version-1.0.0/index.md new file mode 100644 index 0000000000..dedcc49df6 --- /dev/null +++ b/docs/components_versioned_docs/version-1.0.0/versioned_docs/version-1.0.0/index.md @@ -0,0 +1,43 @@ +--- +title: Component Library +sidebar_position: 1 +--- + +# Superset Component Library (v1.0.0) + +Welcome to the Apache Superset Component Library documentation. This section provides comprehensive documentation for all the UI components, chart components, and layout components used in Superset. + +## What is the Component Library? + +The Component Library is a collection of reusable UI components that are used to build the Superset user interface. These components are designed to be consistent, accessible, and easy to use. + +## Component Categories + +The Component Library is organized into the following categories: + +### UI Components + +Basic UI components like buttons, inputs, dropdowns, and other form elements. + +### Chart Components + +Visualization components used to render different types of charts and graphs. + +### Layout Components + +Components used for page layout, such as containers, grids, and navigation elements. + +## Versioning + +The Component Library documentation follows its own versioning scheme, independent from the main Superset documentation. This allows us to update the component documentation as the components evolve, without affecting the main documentation. + +This is version 1.0.0 of the Component Library documentation. + +## Getting Started + +Browse the sidebar to explore the different components available in the library. Each component documentation includes: + +- Component description and purpose +- Props and configuration options +- Usage examples +- Best practices diff --git a/docs/components_versioned_docs/version-1.0.0/versioned_docs/version-1.0.0/introduction.md b/docs/components_versioned_docs/version-1.0.0/versioned_docs/version-1.0.0/introduction.md new file mode 100644 index 0000000000..dedcc49df6 --- /dev/null +++ b/docs/components_versioned_docs/version-1.0.0/versioned_docs/version-1.0.0/introduction.md @@ -0,0 +1,43 @@ +--- +title: Component Library +sidebar_position: 1 +--- + +# Superset Component Library (v1.0.0) + +Welcome to the Apache Superset Component Library documentation. This section provides comprehensive documentation for all the UI components, chart components, and layout components used in Superset. + +## What is the Component Library? + +The Component Library is a collection of reusable UI components that are used to build the Superset user interface. These components are designed to be consistent, accessible, and easy to use. + +## Component Categories + +The Component Library is organized into the following categories: + +### UI Components + +Basic UI components like buttons, inputs, dropdowns, and other form elements. + +### Chart Components + +Visualization components used to render different types of charts and graphs. + +### Layout Components + +Components used for page layout, such as containers, grids, and navigation elements. + +## Versioning + +The Component Library documentation follows its own versioning scheme, independent from the main Superset documentation. This allows us to update the component documentation as the components evolve, without affecting the main documentation. + +This is version 1.0.0 of the Component Library documentation. + +## Getting Started + +Browse the sidebar to explore the different components available in the library. Each component documentation includes: + +- Component description and purpose +- Props and configuration options +- Usage examples +- Best practices diff --git a/docs/components_versioned_docs/version-1.0.0/versioned_docs/version-1.0.0/layout-components/grid.md b/docs/components_versioned_docs/version-1.0.0/versioned_docs/version-1.0.0/layout-components/grid.md new file mode 100644 index 0000000000..70d8a1bbb5 --- /dev/null +++ b/docs/components_versioned_docs/version-1.0.0/versioned_docs/version-1.0.0/layout-components/grid.md @@ -0,0 +1,95 @@ +--- +title: Grid (v1.0.0) +sidebar_position: 1 +--- + +# Grid Component + +The Grid component provides a flexible layout system for arranging content in rows and columns. + +## Props + +| Prop | Type | Default | Description | +|------|------|---------|-------------| +| `gutter` | `number` or `[number, number]` | `0` | Grid spacing between items, can be a single number or [horizontal, vertical] | +| `columns` | `number` | `12` | Number of columns in the grid | +| `justify` | `string` | `'start'` | Horizontal alignment: 'start', 'center', 'end', 'space-between', 'space-around' | +| `align` | `string` | `'top'` | Vertical alignment: 'top', 'middle', 'bottom' | +| `wrap` | `boolean` | `true` | Whether to wrap items when they overflow | + +### Row Props + +| Prop | Type | Default | Description | +|------|------|---------|-------------| +| `gutter` | `number` or `[number, number]` | `0` | Spacing between items in the row | +| `justify` | `string` | `'start'` | Horizontal alignment for this row | +| `align` | `string` | `'top'` | Vertical alignment for this row | + +### Col Props + +| Prop | Type | Default | Description | +|------|------|---------|-------------| +| `span` | `number` | - | Number of columns the grid item spans | +| `offset` | `number` | `0` | Number of columns the grid item is offset | +| `xs`, `sm`, `md`, `lg`, `xl` | `number` or `object` | - | Responsive props for different screen sizes | + +## Examples + +### Basic Grid + +```jsx +import { Grid, Row, Col } from '@superset-ui/core'; + +function Example() { + return ( + <Grid> + <Row gutter={16}> + <Col span={8}> + <div>Column 1</div> + </Col> + <Col span={8}> + <div>Column 2</div> + </Col> + <Col span={8}> + <div>Column 3</div> + </Col> + </Row> + </Grid> + ); +} +``` + +### Responsive Grid + +```jsx +import { Grid, Row, Col } from '@superset-ui/core'; + +function Example() { + return ( + <Grid> + <Row gutter={[16, 24]}> + <Col xs={24} sm={12} md={8} lg={6}> + <div>Responsive Column 1</div> + </Col> + <Col xs={24} sm={12} md={8} lg={6}> + <div>Responsive Column 2</div> + </Col> + <Col xs={24} sm={12} md={8} lg={6}> + <div>Responsive Column 3</div> + </Col> + <Col xs={24} sm={12} md={8} lg={6}> + <div>Responsive Column 4</div> + </Col> + </Row> + </Grid> + ); +} +``` + +## Best Practices + +- Use the Grid system for complex layouts that need to be responsive +- Specify column widths for different screen sizes to ensure proper responsive behavior +- Use gutters to create appropriate spacing between grid items +- Keep the grid structure consistent throughout your application +- Consider using the grid system for dashboard layouts to ensure consistent spacing and alignment diff --git a/docs/components_versioned_docs/version-1.0.0/versioned_docs/version-1.0.0/ui-components/button.md b/docs/components_versioned_docs/version-1.0.0/versioned_docs/version-1.0.0/ui-components/button.md new file mode 100644 index 0000000000..e762909957 --- /dev/null +++ b/docs/components_versioned_docs/version-1.0.0/versioned_docs/version-1.0.0/ui-components/button.md @@ -0,0 +1,60 @@ +--- +title: Button (v1.0.0) +sidebar_position: 1 +--- + +# Button Component + +The Button component is a fundamental UI element used throughout Superset for user interactions. + +## Props + +| Prop | Type | Default | Description | +|------|------|---------|-------------| +| `buttonStyle` | `string` | `'primary'` | Button style: 'primary', 'secondary', 'link', 'dashed', 'danger' | +| `buttonSize` | `string` | `'default'` | Button size: 'small', 'default', 'large' | +| `disabled` | `boolean` | `false` | Whether the button is disabled | +| `onClick` | `function` | - | Callback when button is clicked | +| `href` | `string` | - | Turns button into an anchor link | +| `target` | `string` | - | Target attribute for anchor links | + +## Examples + +### Basic Button + +```jsx +import { Button } from '@superset-ui/core'; + +function Example() { + return ( + <Button buttonStyle="primary" onClick={() => console.log('Clicked!')}> + Click Me + </Button> + ); +} +``` + +### Button Styles + +```jsx +import { Button } from '@superset-ui/core'; + +function Example() { + return ( + <> + <Button buttonStyle="primary">Primary</Button> + <Button buttonStyle="secondary">Secondary</Button> + <Button buttonStyle="link">Link</Button> + <Button buttonStyle="dashed">Dashed</Button> + <Button buttonStyle="danger">Danger</Button> + </> + ); +} +``` + +## Best Practices + +- Use primary buttons for the main action in a form or page +- Use secondary buttons for alternative actions +- Limit the number of primary buttons on a page to avoid confusion +- Use consistent button styles throughout your application diff --git a/docs/components_versioned_docs/version-1.0.0/versions.json b/docs/components_versioned_docs/version-1.0.0/versions.json new file mode 100644 index 0000000000..5e1abcd8a6 --- /dev/null +++ b/docs/components_versioned_docs/version-1.0.0/versions.json @@ -0,0 +1,3 @@ +[ + "1.0.0" +] diff --git a/docs/components_versioned_sidebars/version-1.0.0-sidebars.json b/docs/components_versioned_sidebars/version-1.0.0-sidebars.json new file mode 100644 index 0000000000..87e987e63c --- /dev/null +++ b/docs/components_versioned_sidebars/version-1.0.0-sidebars.json @@ -0,0 +1,39 @@ +{ + "ComponentSidebar": [ + { + "type": "doc", + "label": "Introduction", + "id": "index" + }, + { + "type": "category", + "label": "UI Components", + "items": [ + { + "type": "autogenerated", + "dirName": "ui-components" + } + ] + }, + { + "type": "category", + "label": "Chart Components", + "items": [ + { + "type": "autogenerated", + "dirName": "chart-components" + } + ] + }, + { + "type": "category", + "label": "Layout Components", + "items": [ + { + "type": "autogenerated", + "dirName": "layout-components" + } + ] + } + ] +} diff --git a/docs/components_versions.json b/docs/components_versions.json new file mode 100644 index 0000000000..5e1abcd8a6 --- /dev/null +++ b/docs/components_versions.json @@ -0,0 +1,3 @@ +[ + "1.0.0" +]