Merge docs to main

This merge mostly contain docs updates

.storybook/preview.scss

@@ -1,52 +1,4 @@
-/* stylelint-disable no-invalid-position-at-import-rule */
-/* stylelint-disable selector-class-pattern */
-@use "../packages/kubrick/scss/base";
-@import '../wordpress/wp-includes/css/dashicons.min.css';
-@import '../wordpress/wp-admin/css/common.min.css';
-@import '../wordpress/wp-admin/css/edit.min.css';
-@import '../wordpress/wp-includes/css/buttons.min.css';
-@import "../wordpress/wp-admin/css/forms.min.css";
-
-// Default.
-.admin-color-modern {
-	@import "../wordpress/wp-admin/css/colors/modern/colors";
-}
-
-.admin-color-blue {
-	@import "../wordpress/wp-admin/css/colors/blue/colors";
-}
-
-.admin-color-coffee {
-	@import "../wordpress/wp-admin/css/colors/coffee/colors";
-}
-
-.admin-color-ectoplasm {
-	@import "../wordpress/wp-admin/css/colors/ectoplasm/colors";
-}
-
-.admin-color-light {
-	@import "../wordpress/wp-admin/css/colors/light/colors";
-}
-
-.admin-color-midnight {
-	@import "../wordpress/wp-admin/css/colors/midnight/colors";
-}
-
-.admin-color-ocean {
-	@import "../wordpress/wp-admin/css/colors/ocean/colors";
-}
-
-.admin-color-sunrise {
-	@import "../wordpress/wp-admin/css/colors/sunrise/colors";
-}
-
-.__wp-core-body__ {
-	min-width: 600px;
-	font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen-Sans, Ubuntu, Cantarell, "Helvetica Neue", sans-serif;
-	line-height: 1.4em;
-	color: #3c434a;
-	background: var(--kubrick-body-background-color);
-}
+@use "../packages/kubrick/scss/preview";
 
 // TODO: Remove this once there's a more reliable way to not affect the Storybook styles.
 .docblock-argstable-body {

packages/kubrick/scss/preview.scss

@@ -0,0 +1,49 @@
+/* stylelint-disable no-invalid-position-at-import-rule */
+/* stylelint-disable selector-class-pattern */
+@use './base';
+@use '../../../wordpress/wp-includes/css/dashicons.css';
+@use '../../../wordpress/wp-includes/css/buttons.css';
+@use '../../../wordpress/wp-admin/css/common.css';
+@use '../../../wordpress/wp-admin/css/edit.css';
+@use "../../../wordpress/wp-admin/css/forms.css";
+
+// Default.
+.admin-color-modern {
+	@import "../../../wordpress/wp-admin/css/colors/modern/colors";
+}
+
+.admin-color-blue {
+	@import "../../../wordpress/wp-admin/css/colors/blue/colors";
+}
+
+.admin-color-coffee {
+	@import "../../../wordpress/wp-admin/css/colors/coffee/colors";
+}
+
+.admin-color-ectoplasm {
+	@import "../../../wordpress/wp-admin/css/colors/ectoplasm/colors";
+}
+
+.admin-color-light {
+	@import "../../../wordpress/wp-admin/css/colors/light/colors";
+}
+
+.admin-color-midnight {
+	@import "../../../wordpress/wp-admin/css/colors/midnight/colors";
+}
+
+.admin-color-ocean {
+	@import "../../../wordpress/wp-admin/css/colors/ocean/colors";
+}
+
+.admin-color-sunrise {
+	@import "../../../wordpress/wp-admin/css/colors/sunrise/colors";
+}
+
+.__wp-core-body__ {
+	min-width: 600px;
+	font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen-Sans, Ubuntu, Cantarell, "Helvetica Neue", sans-serif;
+	line-height: 1.4em;
+	color: #3c434a;
+	background: var(--kubrick-body-background-color);
+}

packages/kubrick/src/Button/Button.stories.tsx

@@ -104,6 +104,14 @@ export const Disabled: Story = {
 	},
 };
 
+export const Loading: Story = {
+	args: {
+		children: 'Loading...',
+		isDisabled: true,
+		prefix: <Spinner />,
+	},
+};
+
 export const WithPrefix: Story = {
 	args: {
 		children: 'Upload',
@@ -118,12 +126,4 @@ export const WithSuffix: Story = {
 	},
 };
 
-export const WithSpinner: Story = {
-	args: {
-		children: 'Loading...',
-		isDisabled: true,
-		prefix: <Spinner />,
-	},
-};
-
 export default meta;

packages/kubrick/src/Providers/PreviewProvider.tsx

@@ -0,0 +1,20 @@
+import '../../scss/preview.scss';
+import { useClasses } from '../useClasses';
+
+interface PreviewProviderProps {
+	children: React.ReactNode;
+	className?: string;
+}
+
+export const PreviewProvider = ({
+	children,
+	className,
+}: PreviewProviderProps) => {
+	const { clsx } = useClasses('PreviewProvider');
+
+	return (
+		<div className={clsx({ classNames: ['__wp-core-body__', className] })}>
+			<div className="wp-core-ui">{children}</div>
+		</div>
+	);
+};

packages/kubrick/src/Providers/index.ts

@@ -0,0 +1 @@
+export * from './PreviewProvider';

packages/kubrick/src/index.ts

@@ -10,6 +10,7 @@ export * from './IconLinkButton';
 export * from './Link';
 export * from './LinkButton';
 export * from './Notice';
+export * from './Providers';
 export * from './RadioGroup';
 export * from './SearchField';
 export * from './Select';

site/src/content/docs/components/box.mdx

@@ -69,10 +69,10 @@ You can also add a footer section to the box by adding the `footer` prop. Though
 	component="Box"
 	prefix="kubrick-Box-"
 	items={[
-		[ 'root', 'The root element of the box.' ],
-		[ 'header', 'The header section containing the title and toggle button.' ],
-		[ 'title', 'The element that wraps the title of the box.' ],
-		[ 'content', 'The content section of the box.' ],
-		[ 'footer', 'The footer section of the box.' ],
+		["root", "The root element of the box."],
+		["header", "The header section containing the title and toggle button."],
+		["title", "The element that wraps the title of the box."],
+		["content", "The content section of the box."],
+		["footer", "The footer section of the box."],
 	]}
 />

site/src/content/docs/components/button.mdx

@@ -4,46 +4,58 @@ description: Learn how to use the Button component in your WordPress admin appli
 ---
 
 import { Aside } from '@astrojs/starlight/components';
+import Lead from "../../templates/Lead.astro";
+import Table from "../../templates/Table.astro";
 
-The `Button` component represents the HTML `button` element to trigger an action or event with mouse, touch, or keyboard. It comes in different styles and sizes that you can choose from. You can also add icons or other type of content before or after the button label.
+<Lead storybook="/?path=/docs/components-button--docs">
+The `Button` component is similar to the HTML `button` element, but with some additional features and flexibilities. You can use this component to allow users to trigger actions or events through clicks, touch, or keyboard input.
+</Lead>
 
 ## Usage
 
-Import the `Button` component from the package:
+To use the component, import `Button` from the package:
 
 ```jsx
 import { Button } from '@syntatis/kubrick';
 ```
 
-To use it in your application, you can add it the same as you would with a native HTML `button` element:
+You can then add it to your app just like a regular HTML `button` element:
 
 ```jsx
 <Button>Save Changes</Button>
 ```
 
-Similar to the native HTML `button` element, the `Button` component will be rendered as the `button` type by default. You can change the type with the `type` prop, for example, to render it as a `submit` button:
+### Type
+
+By default, the `Button` component behaves like a standard HTML `button`. You can change the button type using the `type` prop, for example, to make it a `submit` button:
 
 ```jsx
 <Button type="submit">Save Changes</Button>
 ```
 
-You can also make the button disabled by passing the `isDisabled` prop. This is useful when the button should not be clickable, for example, when the form is not valid or when the user does not have the right permission to perform the action.
+### Disabled
+
+To disable the button, use the `isDisabled` prop. This is helpful when the button shouldn't be clickable, such as when a form is incomplete or the user lacks permission to perform an action.
 
 ```jsx
 <Button isDisabled>Save Changes</Button>
 ```
 
+<Aside>
+A **disabled** button is non-interactive. It will disappear from the tab order that users won't be able to interact with it using keyboard, and it won't emit any events.
+</Aside>
+
 ### Variants
 
-The `Button` component comes with different variants that you can choose from. The default variant is `primary`, but you can change it to `link`, `link-danger`, and `secondary` to match the button appearance with its function.
+The `Button` component comes with different style variants, and can be customized using the `variant` prop. The default variant of the component is `primary`, but you can switch to `link`, `link-danger`, or `secondary` to suit the button's role.
 
 ```jsx
 <Button variant="secondary">Create new</Button>
 ```
 
 ### Sizes
 
-Aside of the variants, the `Button` component also comes with different sizes that you can choose from. You can change it to `small`, `large`, and `hero` to match the appareance with its significance or with the surrounding sizes.
+You can also choose from different button sizes. You can change it using the `size` prop to `small`, `large`, or `hero` following on the context or importance of the button.
 
 ```jsx
 <Button size="small">View</Button>
@@ -53,28 +65,22 @@ Aside of the variants, the `Button` component also comes with different sizes th
 
 The `Button` components comes with `prefix` and `suffix` props to to allow you to add content before or after the button label. You can add any type of content, but typically you would use these props to add icons.
 
-Kubrick UI does not come with its own icon library. You can use any icon library you prefer, though we recommend using the [`@wordpress/icons`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-icons/) or [Dashicons](https://developer.wordpress.org/resource/dashicons/) to make your WordPress admin application remains consistent with the WordPress admin interface.
-
 ```jsx
-import { Icon } from '@wordpress/icons';
+import { Icon, edit } from '@wordpress/icons';
 
-<Button suffix={<Icon name="save" />}>
-	Save Settings
+// Add an icon after the button label
+<Button suffix={<Icon icon={edit} />}>
+	Edit
 </Button>
-```
-
-#### Using Dashicons
-
-The Dashicons icons are integrated into the WordPress admin interface. You can use them in your WordPress admin application by adding the Dashicons class to the `span` element, for example:
 
-```jsx
-<Button suffix={<span class="dashicons dashicons-admin-settings" />}>
-	Save Settings
+// Add an icon before the button label
+<Button prefix={<Icon icon={edit} />}>
+	Edit
 </Button>
 ```
 
-<Aside type="caution">
-The Dashicons project is no longer actively maintained. The icon collection is pretty limited and there won't be new icons added into the library. We always recommend using the `@wordpress/icons` package whenever it is possible.
+<Aside type="tip">
+The `@wordpress/icons` package is recommended for use in WordPress admin applications. You can also use Dashicons, which is already included in the WordPress admin interface. See the [Icons guide](/docs/guides/icons) for more information.
 </Aside>
 
 ### Loading
@@ -89,15 +95,19 @@ When the button is on the loading state, it will show a spinner and the button w
 
 ## Events
 
-The `Button` component will emit an event when user interacts with it, such as when the button is clicked, hover, or on focus. You can handle these events by passing function to the following props:
+<Table
+	variant="events"
+	component="Button"
+	items={[
+		[ 'onPress', 'Triggered when the button is clicked. It receives the click event as an argument.' ],
+		[ 'onHoverChange', 'Triggered when the button is hovered. It will receive a boolean indicating if the button is hovered.' ],
+		[ 'onFocusChange', 'Triggered when the button receives or loses focus. It will receive a boolean indicating if the button is focused.' ],
+	]}
+/>
 
-| Prop | Description |
-| --- | --- |
-| `onPress` | Triggered when the button is clicked. |
-| `onHoverChange` | Triggered when the button is hovered. |
-| `onFocusChange` | Triggered when the button receives or loses focus. |
+Let's assume you have an app with the `Button` component to save or updates settings. When the user click on it, you want to show the loading state and disable the button to prevent multiple clicks.
 
-Let's assume we have an app. When the user click the button to save their updates, we want to show the loading state and disable the button to prevent multiple clicks. We can handle this by using the `onPress` event:
+You can achieve that by using the `onPress` prop to handle the click event and add the `loading` prop to show the loading state.
 
 ```jsx {18} collapse={8-12}
 import { useState } from 'react';
@@ -127,13 +137,14 @@ function SaveButton() {
 
 ## Styles
 
-The `Button` component comes with a few static selectors, prefixed with `.kubrick-Button-`, that you can use to select and customize the component and its elements.
-
-<div className="table-classes">
-| Selector | Description |
-| --- | --- |
-| `root` | The root element of the button. |
-| `prefix` | The element that wraps the prefix content. |
-| `suffix` | The element that wraps the suffix content. |
-| `infix` | The element that wraps the button label when the prefix or suffix is present. |
-</div>
+<Table
+	variant="classes"
+	component="Button"
+	prefix="kubrick-Button-"
+	items={[
+		[ 'root', 'The root element of the button.' ],
+		[ 'prefix', 'The wrapper element of the prefix content.' ],
+		[ 'suffix', 'The wrapper element of the suffix content.' ],
+		[ 'infix', 'The wrapper element of the button label, when the prefix or suffix is present.' ],
+	]}
+/>