fluent-svelte-extra 1.0.0

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

@@ -0,0 +1,188 @@
+<script lang="ts">
+    import { CalendarView, ComboBox, InfoBar } from "$lib";
+    import { CalendarViewItem } from "$lib/internal";
+    import { Showcase, APIDocs } from "$site/lib";
+
+    import data from "$lib/CalendarView/CalendarView.svelte?sveld&raw";
+
+    let viewExample = "days";
+</script>
+
+A calendar view lets a user view and interact with a calendar that they can navigate by month, year, or decade. A user can select a single date or multiple dates.
+
+```ts
+import { CalendarView } from "fluent-svelte";
+```
+
+<Showcase style="block-size: 480px">
+    <CalendarView on:keydown={e => e.stopPropagation()} on:dblclick={e => e.stopPropagation()} on:mousedown={e => e.stopPropagation()} />
+</Showcase>
+
+## Usage
+
+### Controlling Value
+
+Selections made in the calendar can be controlled using the `value` property, which outputs a `Date` object or array of `Date` objects. When the user clicks an item in the calendar, the `value` property is updated to reflect the selection. `value` can also be `null` or `undefined` to indicate no selection or a selection cleared by the user.
+
+This CalendarView will be initialized with a value of March 3, 2020.
+
+```svelte hideScript
+<CalendarView value={new Date(2020, 2, 3)} />
+```
+
+You can also use two-way binding to programatically work with the value of the calendar.
+
+```svelte example
+<script>
+	import { Button, CalendarView } from "fluent-svelte";
+
+	let value = new Date(); // The current date
+</script>
+
+<CalendarView bind:value />
+
+Current value: {value?.toLocaleDateString()}
+
+<Button on:click={() => (value = null)}>Clear Value</Button>
+```
+
+### Multiple Selections
+
+CalendarView can also accept more than one value. To initially select multiple dates, pass an array of `Date` objects to the `value` property rather than a single `Date`.
+
+```svelte
+<CalendarView value={[new Date(2022, 2, 3), new Date(2022, 2, 4)]} />
+```
+
+This will render the calendar with March 3 and 4 selected, but as soon as the user attempts to choose another date, the previous selections will be cleared and `value` will be set back to a single date that the user chooses.
+
+To allow the user to pick multiple dates at once, set the `multiple` property to `true`.
+
+```svelte example hideScript
+<script>
+	import { CalendarView } from "fluent-svelte";
+</script>
+
+<CalendarView multiple value={[new Date(2022, 2, 3), new Date(2022, 2, 4)]} />
+```
+
+<InfoBar title="Multiple selections will always be arrays." severity="caution">
+    In multiple mode, the <code>value</code> property will always be an array of <code>Date</code>s. If you pass a single date into <code>value</code> initially in multiple mode, it will be converted to an array containing that date once a second selection is made.
+</InfoBar>
+
+### Minimum and Maximum Values
+
+You can limit the range of dates that can be selected by the user using the `min` and `max` properties. These properties are both `Date` objects representing the earliest and latest dates that can be selected. If the user attempts to click a date outside of the range, the calendar will not allow the selection.
+
+In this example, the user will only be able to select dates in the year of 2020.
+
+```svelte example hideScript
+<script>
+	import { CalendarView } from "fluent-svelte";
+</script>
+
+<CalendarView min={new Date(2020, 0, 1)} max={new Date(2020, 11, 31)} />
+```
+
+### Localization
+
+Many elements of a calendar need to vary across languages. By default, the calendar automatically localizes itself based on the browser's `navigator.language` using the [`Intl.DateTimeFormat` API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat).
+
+If you only want the calendar to render in a specific locale, you can pass in a locale string to the `locale` property.
+
+```svelte example hideScript
+<script>
+	import { CalendarView } from "fluent-svelte";
+</script>
+
+<CalendarView locale="ja-JP" />
+```
+
+Many places additionally have different starting days of the week. The JavaScript `Date` object starts it's weeks on Sunday, but you can customize the starting day of the calendar's week using the `weekStart` property. `weekStart` accepts a number between 0 and 6 (zero is sunday, six is saturday).
+
+```svelte example hideScript
+<script>
+	import { CalendarView } from "fluent-svelte";
+</script>
+
+<!-- Week will start on Monday (1) instead of Sunday (0). -->
+<CalendarView weekStart={1} />
+```
+
+### "Blackout" Dates
+
+In some cases, it might be desirable to prevent the user from selecting a specific day (or days) in the calendar. This can be done by passing in an array of dates to the `blackout` property.
+
+<InfoBar severity="information" title="This property only affects user interaction.">
+    Dates excluded using the <code>blackout</code> property do not affect <i>you</i>, the developer from manually setting values to those dates. This propertly only prevents the user from conventionally picking excluded dates themselves.
+</InfoBar>
+
+In this example, the user will be able to select all dates _except_ for March 7, 2022 and March 9, 2022.
+
+```svelte example hideScript
+<script>
+	import { CalendarView } from "fluent-svelte";
+</script>
+
+<CalendarView
+	value={new Date(2022, 2, 1)}
+	blackout={[new Date(2022, 2, 7), new Date(2022, 2, 9)]}
+/>
+```
+
+### Views
+
+To aid with navigating long ranges of dates, a user can click the CalendarView's main header to switch the _view_. This lets the user quickly navigate through days, months, or years.
+
+<ComboBox style="margin-block-end: 12px; min-inline-size: 100px;" bind:value={viewExample} placeholder="View" items={[
+{
+name: "days",
+value: "days"
+},
+{
+name: "months",
+value: "months"
+},
+{
+name: "years",
+value: "years"
+}
+]} />
+
+<br />
+
+<CalendarView bind:view={viewExample} />
+
+<br /><br />
+
+You can control the current view that the calendar is in using the `view` property, which can be set to either `days`, `months`, or `years`. Setting the `view` property will not prevent the user from manually changing the view by clicking the header.
+
+For example, this will start the calendar in the `months` view:
+
+```svelte
+<CalendarView view="months" />
+```
+
+### Item Headers
+
+You can choose display indicator labels for the first day of a month, or first month of a year (depending on the current view) by setting the `headers` property.
+
+-   When in days view, the first day of a given month will have a header with the month's name above it.
+-   When in months view, the first month of a given year will have the year labeled above it.
+
+```svelte example hideScript
+<script>
+	import { CalendarView } from "fluent-svelte";
+</script>
+
+<CalendarView headers />
+```
+
+| No Headers                                                                                                                                  | Headers                                                                                                                                                                |
+| ------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <CalendarViewItem current>1</CalendarViewItem> <CalendarViewItem selected>1</CalendarViewItem>                                              | <CalendarViewItem current header="Jan">1</CalendarViewItem> <CalendarViewItem selected header="Jan">1</CalendarViewItem>                                               |
+| <CalendarViewItem current variant="monthYear">Jan</CalendarViewItem> <CalendarViewItem  selected variant="monthYear">Jan</CalendarViewItem> | <CalendarViewItem current variant="monthYear" header="2022">Jan</CalendarViewItem> <CalendarViewItem selected variant="monthYear" header="2022">Jan</CalendarViewItem> |
+
+## Component API
+
+<APIDocs manualForward {data} />

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

@@ -0,0 +1,87 @@
+<script lang="ts">
+    import { Checkbox, Button, InfoBar } from "$lib";
+    import { Showcase, APIDocs } from "$site/lib";
+
+    import data from "$lib/Checkbox/Checkbox.svelte?sveld&raw";
+</script>
+
+Checkboxes represent a control that a user can select (check) or clear (uncheck). A Checkbox can also report its value as indeterminate.
+
+```ts
+import { Checkbox } from "fluent-svelte";
+```
+
+<Showcase columns={3} repl="f749a248f8924ea3a90db238cc2c2415">
+    <Checkbox>Checkbox</Checkbox>
+    <Checkbox checked>Checkbox</Checkbox>
+    <Checkbox checked indeterminate>Checkbox</Checkbox>
+    <Checkbox disabled>Checkbox</Checkbox>
+    <Checkbox checked disabled>Checkbox</Checkbox>
+    <Checkbox checked disabled indeterminate>Checkbox</Checkbox>
+</Showcase>
+
+## Usage
+
+`<Checkbox />` is a wrapper around HTML's `<input />` checkbox type. As such, the APIs share some similarities.
+
+### Checking and Unchecking
+
+You can programmatically control if the checkbox is in it's checked state by setting the `checked` property.
+
+```svelte example hideScript
+<script>
+	import { Checkbox } from "fluent-svelte";
+</script>
+
+<Checkbox checked />
+```
+
+Additionally, you can use svelte's two-way binding syntax to bind the checked state to a variable.
+
+```svelte example
+<script>
+	import { Checkbox } from "fluent-svelte";
+
+	let checked = false;
+</script>
+
+<Checkbox bind:checked />
+
+Current state: {checked ? "checked" : "unchecked"}
+```
+
+### Indeterminate States
+
+If the checkbox cannot be represented as either checked or unchecked, it can be marked as _indeterminate_ using the `indeterminate` property.
+
+```svelte example hideScript
+<script>
+	import { Checkbox } from "fluent-svelte";
+</script>
+
+<Checkbox indeterminate />
+```
+
+### Labels
+
+Passing in content to the checkbox's slot will cause that content to be rendered into a label for the control.
+
+```svelte example hideScript
+<script>
+	import { Checkbox } from "fluent-svelte";
+</script>
+
+<Checkbox>I have a label!</Checkbox>
+```
+
+### Value
+
+For usage in forms, you can set a `value` property which will set the [value](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#value) of the Checkbox's `<input>` element.
+
+### Disabled Checkboxes
+
+If the checkbox is not meant to be clicked, you can use the `disabled` property to visually indicate this. If a checkbox is disabled, it will be unclickable.
+
+## Component API
+
+<APIDocs {data} />

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

@@ -0,0 +1,155 @@
+<script lang="ts">
+    import { Button, ContentDialog, InfoBar } from "$lib";
+    import { Showcase, APIDocs } from "$site/lib";
+
+    import data from "$lib/ContentDialog/ContentDialog.svelte?raw&sveld";
+
+    let open = true;
+
+    const sizes = {
+        min: 320,
+        standard: 448,
+        max: 540
+    }
+</script>
+
+Dialog controls are modal UI overlays that provide contextual app information. They block interactions with the app window until being explicitly dismissed. They often request some kind of action from the user.
+
+```ts
+import { ContentDialog } from "fluent-svelte";
+```
+
+<Showcase style="block-size: 360px;" repl="0fde4983fdc841d8b7320143ee3d50d7">
+    <Button on:click={() => open = true}>
+        Open
+    </Button>
+    <ContentDialog bind:open trapFocus={false} darken={false} title="Dialog Title">
+        Some text
+        <svelte:fragment slot="footer">
+            <Button variant="accent" on:click={() => open = false}>
+                Button 1
+            </Button>
+            <Button on:click={() => open = false}>
+                Button 2
+            </Button>
+        </svelte:fragment>
+    </ContentDialog>
+</Showcase>
+
+## Usage
+
+### Opening and Closing
+
+Dialogs are not rendered into the DOM initially. They need to be _opened_ first, by setting the `open` property.
+
+```svelte
+<ContentDialog open>This dialog is open by default.</ContentDialog>
+```
+
+If you wish to control a dialog opening from a trigger button, you can two-way bind the `open` property to a variable.
+
+```svelte example
+<script>
+	import { ContentDialog, Button } from "fluent-svelte";
+
+	let open = false;
+</script>
+
+<Button on:click={() => (open = true)}>Open Dialog</Button>
+
+<ContentDialog bind:open>
+	I have been opened by a button click.
+	<Button on:click={() => (open = false)}>Close</Button>
+</ContentDialog>
+```
+
+Additionally, dialogs can be closed by pressing the escape key. If you wish to disable this behavior, you can set the `closable` property to `false`.
+
+### Titles
+
+While not strictly required, it is recommended that you give the dialog a title to describe it's purpose using the `title` property. This both visually adds a title at the top of the content area, and adds an accessible label through ARIA attributes for usage with assistive technologies.
+
+```svelte
+<ContentDialog title="I have a title." />
+```
+
+<InfoBar title="A11Y Note" severity="caution">
+    The ARIA 1.2 specification requires a dialog title in order to comply with the <a href="https://www.w3.org/TR/wai-aria-practices/#dialog_modal" target="_blank" rel="noreferrer noopener">modal dialog pattern</a>.
+</InfoBar>
+
+### Footers
+
+You can use the `footer` slot to insert various actions at the bottom of the dialog.
+
+```svelte
+<script>
+	import { ContentDialog, Button } from "fluent-svelte";
+
+	let open = true;
+</script>
+
+<ContentDialog bind:open title="Dialog with action">
+	<Button slot="footer" on:click={() => (open = false)}>Close Dialog</Button>
+</ContentDialog>
+```
+
+### Size
+
+Dialogs come in three sizes - `min`, `standard`, and `max`. You can set the dialog's size using the `size` property. With this in mind, dialogs will always responsively scale down if their width exceeds the viewport size.
+
+<div class="dialog-sizes">
+    {#each ["min", "standard", "max"] as size}
+        <ContentDialog title="This is a {size}-sized dialog." trapFocus={false} {size} open>
+            It has a width of {sizes[size]}px.
+            <Button slot="footer">Action</Button>
+        </ContentDialog>
+    {/each}
+</div>
+
+### Dialog Backdrops
+
+The default behavior of a dialog is to open with a backdrop ("smoke") layer which prevents user interaction and darkens the contents of the page behind the dialog.
+
+-   You can disable backdrop darkening by setting the `darken` property to `false`.
+-   You can configure the backdrop to close the dialog when it is clicked using the `on:backdropclick` and `on:backdropmousedown` events dispatched from the component.
+
+### Focus Behavior
+
+In accordance to [WAI-ARIA Authoring Practices](https://www.w3.org/TR/wai-aria-practices/#keyboard-interaction-7), dialogs utilize a focus trap, which restricts keyboard navigation focus to only the dialog's content. If you wish to disable this behavior, you can set the `trapFocus` property to `false`.
+
+### Appending
+
+There are some situations where you might want the dialog's elements to open appended to a specific element, separate from your markup structure. This can be useful if you want to trigger the dialog from inside a container element that has `overflow: hidden;` styles set, or if you want a single source of where dialogs should be opened from.
+
+To do this, you can set the `append` property to any valid [HTMLElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement). This will append the dialog to the specified element when opened, rather than the position specified in your markup.
+
+```svelte
+<ContentDialog title="Appended Dialog" append={document.body}>
+	When opened, I will be appended to this page's <body> tag. </body></ContentDialog
+>
+```
+
+<InfoBar severity="information" title="Information">
+    If you are familliar with React, this is essentially a <a href="https://reactjs.org/docs/portals.html" target="_blank" rel="noreferrer noopener">portal</a>.
+</InfoBar>
+
+## Component API
+
+<APIDocs {data} />
+
+<style lang="scss">
+    .dialog-sizes {
+        display: grid;
+        justify-content: start;
+        grid-gap: 24px;
+        margin-block-end: 64px;
+        :global {
+            .content-dialog {
+                position: relative;
+                &-smoke {
+                    display: contents;
+                }
+            }
+        }
+    }
+</style>

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

@@ -0,0 +1,115 @@
+<script lang="ts">
+    import { Expander } from "$lib";
+    import { Showcase, APIDocs } from "$site/lib";
+
+    import Circle from "@fluentui/svg-icons/icons/circle_16_regular.svg?raw";
+
+    import data from "$lib/Expander/Expander.svelte?raw&sveld";
+</script>
+
+Expanders are controls that display a header and a collapsable content area. The content area can be expanded clicking on the header.
+
+```ts
+import { Expander } from "fluent-svelte";
+```
+
+<Showcase style="block-size: 360px;" repl="78aa3269aba34022a958311963520428">
+    <Expander>
+        Expander
+        <svelte:fragment slot="content">
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+        </svelte:fragment>
+    </Expander>
+    <Expander>
+        <svelte:fragment slot="icon">
+            {@html Circle}
+        </svelte:fragment>
+        Expander
+        <svelte:fragment slot="content">
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+        </svelte:fragment>
+    </Expander>
+    <Expander direction="up">
+        Expander
+        <svelte:fragment slot="content">
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+        </svelte:fragment>
+    </Expander>
+</Showcase>
+
+## Usage
+
+A basic expander expects a header and contents. The expander's default slot will be rendered into the header, while content can be rendered into the `content` slot.
+
+```svelte example
+<script>
+	import { Expander } from "fluent-svelte";
+</script>
+
+<Expander>
+	Header
+	<svelte:fragment slot="content">Content</svelte:fragment>
+</Expander>
+```
+
+### Controlling Expansion
+
+Expanders can be either expanded or collapsed. This can be controlled by setting the `expanded` property.
+
+```svelte example
+<script>
+	import { Expander } from "fluent-svelte";
+</script>
+
+<Expander expanded>
+	I am expanded by default.
+	<svelte:fragment slot="content">
+		Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+	</svelte:fragment>
+</Expander>
+```
+
+### Directions
+
+An expander doesn't have to expand downwards. You can control an expander's expansion direction using the `direction` property. To create an upwards-expanding expander, set `direction` to `up`.
+
+```svelte example
+<script>
+	import { Expander } from "fluent-svelte";
+</script>
+
+<Expander direction="up">
+	This expander will expand upwards.
+	<svelte:fragment slot="content">
+		Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+	</svelte:fragment>
+</Expander>
+```
+
+### Adding an Icon
+
+You can easily add an icon to an expander's header using the `icon` slot. Passing in an SVG element will render it into the header with 16x16 dimensions.
+
+```svelte example hideScript
+<script>
+	import { Expander } from "fluent-svelte";
+</script>
+
+<Expander>
+	<!-- 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>
+	Expander
+	<svelte:fragment slot="content">
+		Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+	</svelte:fragment>
+</Expander>
+```
+
+## Component API
+
+<APIDocs {data} />

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

@@ -0,0 +1,107 @@
+<script lang="ts">
+    import { Flyout, Button, ComboBox, Slider } from "$lib";
+    import { Showcase, APIDocs } from "$site/lib";
+
+    import data from "$lib/Flyout/FlyoutWrapper.svelte?raw&sveld";
+
+    const placements = ["top", "bottom", "left", "right"];
+    const alignments = ["start", "center", "end"];
+
+    const positions = placements.flatMap(placement => alignments.map(alignment => ({ placement, alignment })));
+
+    let offset = 0;
+    let placement = "top";
+    let alignment = "center";
+</script>
+
+Flyouts represent a control that displays lightweight UI that is either information, or requires user interaction. Unlike a [ContentDialog](contentdialog), a Flyout can be dismissed by clicking or tapping outside of it, or pressing the <kbd>Esc</kbd> key.
+
+```ts
+import { Flyout } from "fluent-svelte";
+```
+
+<Showcase repl="f884a63a8b3349e38c783e86aa4f4d17">
+    <Flyout open trapFocus={false}>
+        <Button>Open</Button>
+        <svelte:fragment slot="flyout">
+            Flyout
+        </svelte:fragment>
+    </Flyout>
+</Showcase>
+
+## Usage
+
+`Flyout` is a wrapper component. Items placed into the default slot will open the flyout when clicked. To insert contents into the flyout itself, you use the `flyout` slot.
+
+```svelte example hideScript
+<script>
+	import { Flyout, Button } from "fluent-svelte";
+</script>
+
+<Flyout>
+	<Button>Trigger Button</Button>
+	<svelte:fragment slot="flyout">Flyout Contents</svelte:fragment>
+</Flyout>
+```
+
+### Opening and Closing
+
+Flyouts will not be rendered into the DOM until they are opened. A flyout can be opened by the user either with keyboard navigation or by clicking items in the flyout's wrapper element.
+
+You can control if the flyout is open using the `open` property.
+
+```svelte
+<Flyout open>
+	<svelte:fragment slot="flyout">This flyout is open by default.</svelte:fragment>
+</Flyout>
+```
+
+You can also use Svelte's two-way binding syntax to programatically open/close a flyout.
+
+```svelte example
+<script>
+	import { Flyout, Button } from "fluent-svelte";
+
+	let open = false;
+</script>
+
+<Flyout bind:open>
+	<Button>Open</Button>
+	<Button on:click={() => (open = false)} slot="flyout">Close</Button>
+</Flyout>
+```
+
+Additionally, flyouts can be closed by pressing the escape key or clicking on contents behind the flyout. If you wish to disable this behavior, you can set the `closable` property to `false`.
+
+### Positioning
+
+There are three aspects to the positioning system of flyouts - `placement`, `alignment`, and `offset`.
+
+-   The `offset` property controls the distance between the flyout and the flyout wrapper in pixels. The default offset is `8`.
+-   The `placement` property is the direction that the flyout will be opened from. This can be either `top`, `bottom`, `left`, or `right`.
+-   The `alignment` property controls either the vertical or horizontal alignment of the flyout along a given placement axis. This can be either `start`, `center`, or `end`.
+
+### Focus Behavior
+
+Flyouts utilize a focus trap, which restricts keyboard navigation focus to only the flyout's content. If you wish to disable this behavior, you can set the `trapFocus` property to `false`.
+
+### Overriding Flyouts
+
+For more niche use cases, you can completely override the flyout element with your own container using the `override` slot.
+
+```svelte example hideScript
+<script>
+	import { Flyout, Button } from "fluent-svelte";
+</script>
+
+<Flyout>
+	<Button>Open</Button>
+	<div slot="override" style="background-color: red; padding: 24px; min-inline-size: 240px;">
+		Custom flyout containers! <button>Hello World!</button>
+	</div>
+</Flyout>
+```
+
+## Component API
+
+<APIDocs {data} />