fluent-svelte-extra 1.0.0

package/src/routes/docs/components/iconbutton.md

@@ -0,0 +1,39 @@
+<script lang="ts">
+    import { IconButton } from "$lib";
+    import { Showcase, APIDocs } from "$site/lib";
+
+    import Circle from "@fluentui/svg-icons/icons/circle_16_regular.svg?raw";
+
+    import data from "$lib/IconButton/IconButton.svelte?raw&sveld";
+</script>
+
+An Icon Button is a clickable control that triggers an immediate action. Unlike the [Button](button) control, it serves the purpose of encapsulating an icon glyph as it's content.
+
+```ts
+import { IconButton } from "fluent-svelte";
+```
+
+<Showcase columns={2} repl="89b152e7c33047768b6c242eb2a6afcb">
+    <IconButton>
+        {@html Circle}
+    </IconButton>
+    <IconButton disabled>
+        {@html Circle}
+    </IconButton>
+</Showcase>
+
+## Usage
+
+While IconButton is not a direct extension of [Button](button), it shares many similarities with it's API.
+
+### Links
+
+An IconButton can either be a clickable action or a link. By default, an IconButton will be rendered as a standard HTML `<button>` element. If an `href` property is provided, the IconButton will be converted into an `<a>` tag.
+
+### Disabled Buttons
+
+If the button is not meant to be clicked, you can use the `disabled` property to visually indicate this. If a button is disabled, it will be unclickable and the `href` property will be ignored.
+
+## Component API
+
+<APIDocs {data} />

package/src/routes/docs/components/infobadge.md

@@ -0,0 +1,54 @@
+<script lang="ts">
+    import { InfoBadge, Button } from "$lib";
+    import { Showcase, APIDocs } from "$site/lib";
+
+    import data from "$lib/InfoBadge/InfoBadge.svelte?raw&sveld";
+
+    const severities = ["information", "attention", "success", "caution", "critical"];
+</script>
+
+InfoBadges are a non-intrusive and intuitive way to display notifications or bring focus to an area within an app - whether that be for notifications, indicating new content, or showing an alert.
+
+```ts
+import { InfoBadge } from "fluent-svelte";
+```
+
+<Showcase repl="ce7c58c352e24e84ad6838663e6dcd4e" columns={5}>
+    {#each severities as severity}
+        <InfoBadge {severity} />
+    {/each}
+    {#each severities as severity}
+        <InfoBadge {severity}>{Math.floor(Math.random() * 10)}</InfoBadge>
+    {/each}
+</Showcase>
+
+## Usage
+
+### Severity
+
+InfoBadges can take in a `severity` prop, which represent the type of information you wish to convey to the user. The default severity is `attention`.
+
+| Severity      | Preview                              |
+| ------------- | ------------------------------------ |
+| `attention`   | <InfoBadge severity="attention" />   |
+| `information` | <InfoBadge severity="information" /> |
+| `success`     | <InfoBadge severity="success" />     |
+| `caution`     | <InfoBadge severity="caution" />     |
+| `critical`    | <InfoBadge severity="critical" />    |
+
+### Custom Content
+
+The default badge glyph can be overrided with your own content. This can be useful if you wish display text, or an alert count. Passing HTML content into the default slot will override the glyph with said content.
+
+```svelte example hideScript
+<script>
+	import { InfoBadge } from "fluent-svelte";
+</script>
+
+<InfoBadge>99</InfoBadge>
+<InfoBadge severity="critical">bazinga</InfoBadge>
+```
+
+## Component API
+
+<APIDocs {data} />

package/src/routes/docs/components/infobar.md

@@ -0,0 +1,102 @@
+<script lang="ts">
+    import { InfoBar, InfoBadge, Button } from "$lib";
+    import { Showcase, APIDocs } from "$site/lib";
+
+    import data from "$lib/InfoBar/InfoBar.svelte?raw&sveld";
+</script>
+
+The InfoBar control is for displaying app-wide status messages to users that are highly visible yet non-intrusive. There are built-in security levels to easily indicate the type of message shown as well as the option to include your own call to action or hyperlink button.
+
+```ts
+import { InfoBar } from "fluent-svelte";
+```
+
+<Showcase repl="789be6a7b377455aab6f44e123885423" columns={2}>
+    <InfoBar title="Title" message="Message">
+        <Button slot="action">Action</Button>
+    </InfoBar>
+    <InfoBar title="Title" message="Message" severity="attention">
+        <Button slot="action" variant="accent">Action</Button>
+    </InfoBar>
+    <InfoBar title="Title" message="Message" closable={false} />
+    <InfoBar title="Title" message="Message" severity="success" />
+    <InfoBar title="Title" message="Message" severity="caution" />
+    <InfoBar title="Title" message="Message" severity="critical" />
+</Showcase>
+
+## Usage
+
+### Text Contents - `title` and `message`
+
+There are two areas of text that can be customized - the title and the message. Both are optional, but at least one is recommended.
+
+-   You can specify a title for the InfoBar using `title` property.
+-   You can set the InfoBar's message using the `message` property.
+
+```svelte example hideScript
+<script>
+	import { InfoBar } from "fluent-svelte";
+</script>
+
+<InfoBar title="Title" message="Message" />
+```
+
+If you need to include HTML content into the message, you can also just use the default slot.
+
+```svelte example hideScript
+<script>
+	import { InfoBar } from "fluent-svelte";
+</script>
+
+<InfoBar>
+	Visit <a href="https://fluent-svelte.vercel.app">Fluent Svelte</a> for some neat fluent design components!
+</InfoBar>
+```
+
+### Severity
+
+InfoBars can take in a `severity` prop, which represent the type of information you wish to convey to the user. The default severity is `information`.
+
+| Severity      | Badge                                | Usage                                                                   | Preview                                                |
+| ------------- | ------------------------------------ | ----------------------------------------------------------------------- | ------------------------------------------------------ |
+| `information` | <InfoBadge severity="information" /> | Non-critical messages containing general information.                   | <InfoBar severity="information" title="Information" /> |
+| `attention`   | <InfoBadge severity="attention" />   | Messages that are non-critical, but still important to the user.        | <InfoBar severity="attention" title="Attention" />     |
+| `success`     | <InfoBadge severity="success" />     | Messages that convey an action that has postively been completed.       | <InfoBar severity="success" title="Success" />         |
+| `caution`     | <InfoBadge severity="caution" />     | Messages that serve to warn the user of a potentially dangerous action. | <InfoBar severity="caution" title="Caution" />         |
+| `critical`    | <InfoBadge severity="critical" />    | Higher-severity messages that convey a dangerous or failed action.      | <InfoBar severity="critical" title="Critical" />       |
+
+### Action Buttons
+
+An action button can be passed in using the `action` slot. It's recommended that you use the [Button](/docs/components/button) component for this, but any HTML element is valid.
+
+```svelte example hideScript
+<script>
+	import { InfoBar, Button } from "fluent-svelte";
+</script>
+
+<InfoBar title="Title" message="Message">
+	<Button slot="action">Action</Button>
+</InfoBar>
+```
+
+### Controlling Visibility
+
+InfoBars by default are `open`. This means that they are rendered into the DOM. When the close button is pressed, they will be removed from the DOM and the `open` property will be set back to `false`.
+
+```svelte example
+<script>
+	import { InfoBar, Button } from "fluent-svelte";
+
+	let open = false;
+</script>
+
+<Button on:click={() => (open = !open)}>
+	{open ? "Close" : "Open"}
+</Button>
+
+<InfoBar title="Title" message="Message" bind:open />
+```
+
+## Component API
+
+<APIDocs {data} />

package/src/routes/docs/components/listitem.md

@@ -0,0 +1,87 @@
+<script lang="ts">
+    import { ListItem } from "$lib";
+    import { Showcase, APIDocs } from "$site/lib";
+
+    import Circle from "@fluentui/svg-icons/icons/circle_16_regular.svg?raw";
+
+    import data from "$lib/ListItem/ListItem.svelte?raw&sveld";
+</script>
+
+List Items display data stacked vertically in a single column. List Items work better for items that have text as a focal point, and for collections that are meant to be read top to bottom (i.e. alphabetically ordered). A few common use cases for List Items include lists of messages and search results.
+
+```ts
+import { ListItem } from "fluent-svelte";
+```
+
+<Showcase repl="">
+    <div style="inline-size: 240px">
+        <ListItem>ListItem</ListItem>
+        <ListItem>
+            <svelte:fragment slot="icon">
+                {@html Circle}
+            </svelte:fragment>
+            ListItem
+        </ListItem>
+        <ListItem selected>ListItem</ListItem>
+        <ListItem disabled>ListItem</ListItem>
+    </div>
+</Showcase>
+
+## Usage
+
+A ListItem is either a general-purpose item or a link. By default, an item will be rendered as a standard HTML `<li>` element. If an `href` property is provided, the item will be converted into an `<a>` tag.
+
+### Selecting Items
+
+An item can be marked as _selected_ to indicate that it a currently active option. To do this, use the `selected` property.
+
+```svelte example hideScript
+<script>
+	import { ListItem } from "fluent-svelte";
+</script>
+
+<ListItem selected>Text</ListItem>
+```
+
+You can also listen to the `select` event, which is dispatched when the `selected` property is changed to a truthy value.
+
+### Disabled Items
+
+If the item is not meant to be clicked, you can use the `disabled` property to visually indicate this. If an item is disabled, it will be unclickable and the `href` prop will be ignored.
+
+```svelte example hideScript
+<script>
+	import { ListItem } from "fluent-svelte";
+</script>
+
+<ListItem disabled>Text</ListItem>
+```
+
+### Adding an Icon
+
+You can easily add an icon to an item using the `icon` slot. Passing in an SVG element will render it before any contents with 16x16 dimensions.
+
+```svelte example hideScript
+<script>
+	import { ListItem } from "fluent-svelte";
+</script>
+
+<ListItem>
+	<!-- https://github.com/microsoft/fluentui-system-icons -->
+	<svg slot="icon" width="16" height="16" viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg">
+		<path
+			d="M7.85355 0.146447C7.65829 -0.0488155 7.34171 -0.0488155 7.14645 0.146447C6.95118 0.341709 6.95118 0.658291 7.14645 0.853553L8.29603 2.00314C4.80056 2.11088 2 4.97839 2 8.5C2 12.0899 4.91015 15 8.5 15C12.0899 15 15 12.0899 15 8.5C15 8.48656 15 8.47313 14.9999 8.45971C14.9983 8.2001 14.7805 8 14.5209 8H14.4782C14.2093 8 14 8.23107 14 8.5C14 11.5376 11.5376 14 8.5 14C5.46243 14 3 11.5376 3 8.5C3 5.53311 5.34917 3.11491 8.28892 3.00398L7.14645 4.14645C6.95118 4.34171 6.95118 4.65829 7.14645 4.85355C7.34171 5.04882 7.65829 5.04882 7.85355 4.85355L9.85355 2.85355C10.0488 2.65829 10.0488 2.34171 9.85355 2.14645L7.85355 0.146447ZM11.8536 6.14645C12.0488 6.34171 12.0488 6.65829 11.8536 6.85355L8.85355 9.85355C8.65829 10.0488 8.34171 10.0488 8.14645 9.85355L6.64645 8.35355C6.45118 8.15829 6.45118 7.84171 6.64645 7.64645C6.84171 7.45118 7.15829 7.45118 7.35355 7.64645L8.5 8.79289L11.1464 6.14645C11.3417 5.95118 11.6583 5.95118 11.8536 6.14645Z"
+			fill="currentColor"
+		/>
+	</svg>
+	Text
+</ListItem>
+```
+
+### ARIA Roles
+
+For the purposes of accessibly adapting ListItems to certain use-cases, a `role` property has been exposed to override the default [ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques) of the item, which is `listitem`.
+
+## Component API
+
+<APIDocs {data} />

package/src/routes/docs/components/personpicture.md

@@ -0,0 +1,125 @@
+<script lang="ts">
+    import { Button, PersonPicture, InfoBadge } from "$lib";
+    import { Showcase, APIDocs } from "$site/lib";
+
+    import data from "$lib/PersonPicture/PersonPicture.svelte?sveld&raw";
+</script>
+
+The person picture control displays the avatar image for a person, if one is available; if not, it displays the person's initials or a generic glyph. You can additionally insert your own badge at the top of the picture, and provide your own inner content.
+
+```ts
+import { PersonPicture } from "fluent-svelte";
+```
+
+<Showcase repl="46c25d4df2414602878cb7a1d7d47194" columns={4}>
+    <PersonPicture src="https://thispersondoesnotexist.com/image" alt="Random person">
+        {Math.random()
+            .toString(36)
+            .replace(/[^a-z]+/g, "")
+            .toUpperCase()
+            .substr(0, 2)}
+    </PersonPicture>
+    <PersonPicture src="https://thispersondoesnotexist.com/image" alt="Random person" size={48} />
+    <PersonPicture>
+        {Math.random()
+            .toString(36)
+            .replace(/[^a-z]+/g, "")
+            .toUpperCase()
+            .substr(0, 2)}
+        <svelte:fragment slot="badge">
+            <InfoBadge>1</InfoBadge>
+        </svelte:fragment>
+    </PersonPicture>
+    <PersonPicture alt="A A A" />
+</Showcase>
+
+## Usage
+
+### Setting a Photo
+
+Similarly to HTML's [`<img />`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img) element, you can set the `src` property to a URL of an image.
+
+```svelte example hideScript
+<script>
+	import { PersonPicture } from "fluent-svelte";
+</script>
+
+<PersonPicture src="https://source.unsplash.com/random" />
+```
+
+It's recommended for both accessibility and fallback purposes that you provide an `alt` property for the image as well. The `alt` attribute is used by screen readers to provide a description of the image to visually impaired users.
+
+```svelte example hideScript
+<script>
+	import { PersonPicture } from "fluent-svelte";
+</script>
+
+<PersonPicture
+	alt="Dog runs through the snow"
+	src="https://images.unsplash.com/photo-1530126483408-aa533e55bdb2"
+/>
+```
+
+Additionally, if `src` is invalid and no slot text is inserted, the alt text will be converted to initials format as a fallback.
+
+```svelte example hideScript
+<script>
+	import { PersonPicture } from "fluent-svelte";
+</script>
+
+<PersonPicture src="not-a-real-domain" alt="John Smith" />
+```
+
+### Custom Text
+
+If no `src` is provided, you can provide your own text to be displayed in the control. The order of display is:
+
+1. If a valid image URL in `src` is provided, it will be displayed.
+2. If the `src` attribute fails to display or is invalid, the text or HTML is passed into the default slot will be displayed.
+3. If `src` is invalid, no slots are used, but an `alt` property is provided, the alt text will be converted to initials format and displayed.
+
+```svelte example hideScript
+<script>
+	import { PersonPicture } from "fluent-svelte";
+</script>
+
+<div style="display: flex; gap: 12px;">
+	<PersonPicture>RDJ</PersonPicture>
+	<PersonPicture src="not-a-real-domain" alt="Robert Downey Jr." />
+</div>
+```
+
+### Badges
+
+You can use the component's `badge` slot to insert an offset element at the top of the picture. It's recommended that you use the [`InfoBadge`](infobadge) component for this.
+
+```svelte example
+<script>
+	import { InfoBadge, PersonPicture } from "fluent-svelte";
+
+	let messages = 4;
+</script>
+
+<PersonPicture src="https://thispersondoesnotexist.com/image" alt="John Smith">
+	<InfoBadge slot="badge">{messages}</InfoBadge>
+</PersonPicture>
+```
+
+### Size
+
+You can control the dimensions of the picture in pixels by setting the `size` property. The default size is `72`.
+
+```svelte example hideScript
+<script>
+	import { PersonPicture } from "fluent-svelte";
+</script>
+
+<PersonPicture size={8} />
+<PersonPicture size={16} />
+<PersonPicture size={32} />
+<PersonPicture size={64} />
+```
+
+## Component API
+
+<APIDocs {data} />

package/src/routes/docs/components/progressring.md

@@ -0,0 +1,83 @@
+<script lang="ts">
+    import { ProgressRing, NumberBox } from "$lib";
+    import { Showcase, APIDocs } from "$site/lib";
+
+    import data from "$lib/ProgressRing/ProgressRing.svelte?sveld&raw";
+
+    let value = Math.floor(Math.random() * 100);
+</script>
+
+ProgressRing provides visual feedback to to the user that a long-running operation is underway. It can mean that the user cannot interact with the app when the progress indicator is visible, and can also indicate how long the wait time might be.
+
+```ts
+import { ProgressRing } from "fluent-svelte";
+```
+
+<Showcase repl="">
+    <div class="ring-spacer">
+        <ProgressRing />
+        <ProgressRing bind:value />
+    </div>
+    <NumberBox
+        on:mousedown={e => e.stopPropagation()}
+        class="example-ring-input"
+        placeholder="%"
+        clearButton={false}
+        min={0}
+        max={100}
+        inline
+        bind:value
+    />
+</Showcase>
+
+## Usage
+
+### Completion Value
+
+The `value` property takes in a number between `0` to `100` that represents the percentage of a task that is completed.
+
+```svelte example hideScript
+<script>
+	import { ProgressRing } from "fluent-svelte";
+</script>
+
+<ProgressRing value={50} />
+```
+
+ProgressRings have two primary states - _determinate_ and _indeterminate_.
+
+A ProgressRing is indeterminate under the following conditions:
+
+-   No `value` is provided.
+-   A `value` is passed in, but it is `undefined`, `null`, or `NaN`.
+
+A determinate ProgressRing displays a completion percentage by filling the ring gradually, while an indeterminate ProgressRing plays a looping spinner animation.
+
+### Size
+
+You can control the diameter of the ring in pixels by setting the `size` property. The default size is `32`.
+
+```svelte example hideScript
+<script>
+	import { ProgressRing } from "fluent-svelte";
+</script>
+
+<ProgressRing size={64} />
+```
+
+## Component API
+
+<APIDocs {data} />
+
+<style>
+    .ring-spacer {
+        display: grid;
+        grid-template-columns: 1fr 1fr;
+        grid-gap: 12px;
+    }
+
+    :global(.component-showcase .component-showcase-grid > .example-ring-input) {
+        margin-block-start: 12px;
+        inline-size: 108px;
+    }
+</style>

package/src/routes/docs/components/radiobutton.md

@@ -0,0 +1,88 @@
+<script lang="ts">
+    import { RadioButton, Button, InfoBar } from "$lib";
+    import { Showcase, APIDocs } from "$site/lib";
+
+    import data from "$lib/RadioButton/RadioButton.svelte?sveld&raw";
+    
+    let group = 1;
+</script>
+
+Radio buttons, also called option buttons, let users select one option from a collection of two or more mutually exclusive, but related, options. The singular behavior of a RadioButtons group distinguishes it from check boxes, which support multi-selection and deselection, or clearing.
+
+```ts
+import { RadioButton } from "fluent-svelte";
+```
+
+<Showcase columns={3} repl="b3c4c774b4b84f948a8a6747e5cf7226">
+    <RadioButton value={1} bind:group>Option 1</RadioButton>
+    <RadioButton value={2} bind:group>Option 2</RadioButton>
+    <RadioButton value={3} bind:group disabled>Option 3</RadioButton>
+    <RadioButton checked>RadioButton</RadioButton>
+    <RadioButton disabled>RadioButton</RadioButton>
+    <RadioButton disabled checked>RadioButton</RadioButton>
+</Showcase>
+
+## Usage
+
+`<RadioButton />` is a wrapper around HTML's `<input />` radio type. As such, the APIs share some similarities.
+
+### Labels
+
+Passing in content to the RadioButton's slot will cause that content to be rendered into a label for the control.
+
+```svelte example hideScript
+<script>
+	import { RadioButton } from "fluent-svelte";
+</script>
+
+<RadioButton>I have a label!</RadioButton>
+```
+
+### Value
+
+The `value` property is used to determine the piece of data that is associated with the radio. This serves two primary purposes:
+
+-   For usage in forms, this [value](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#value) is submitted with the form as [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData).
+-   If a [group binding](#radio-groups) is used, the radio's `value` will be used to determine which radio in the group is currently selected.
+
+```svelte example hideScript
+<script>
+	import { RadioButton } from "fluent-svelte";
+</script>
+
+<RadioButton value={1}>Option 1</RadioButton>
+```
+
+### Radio Groups
+
+Radio Buttons can be grouped together as a mutually-exclusive list of options using a _group binding_. Group bindings bind to a variable who's value corresponds to the value property of the currently selected item.
+
+```svelte example
+<script>
+	import { RadioButton } from "fluent-svelte";
+
+	let flavor = "chocolate";
+</script>
+
+<RadioButton bind:group={flavor} value="chocolate">Chocolate</RadioButton>
+<RadioButton bind:group={flavor} value="vanilla">Vanilla</RadioButton>
+<RadioButton bind:group={flavor} value="strawberry">Strawberry</RadioButton>
+```
+
+When a RadioButton is selected, it will deselect all other RadioButtons in the same group, then set the bound variable to the selected item's `value` property. If you do not wish to set a default option, the bound variable can simply be initialized without a value.
+
+### Manually Controlling State
+
+If `group` is not set, you also have access to a `checked` property that allows you to manually set the initial state of the Radio.
+
+```svelte example hideScript
+<script>
+	import { RadioButton } from "fluent-svelte";
+</script>
+
+<RadioButton checked>I am checked by default.</RadioButton>
+```
+
+## Component API
+
+<APIDocs {data} />