@atlaskit/date-label 0.1.0

package/CHANGELOG.md

@@ -0,0 +1 @@
+# @atlaskit/date-label

package/LICENSE.md

@@ -0,0 +1,11 @@
+Copyright 2023 Atlassian Pty Ltd
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in
+compliance with the License. You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under the License is
+distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied. See the License for the specific language governing permissions and limitations under the
+License.

package/README.md

@@ -0,0 +1,128 @@
+# DateLabel
+
+A Date label is a non-interactive label that displays a date and optionally, visually communicates
+its status.
+
+## Installation
+
+```sh
+yarn add @atlaskit/date-label
+```
+
+## Usage
+
+### DateLabel
+
+```tsx
+import DateLabel from '@atlaskit/date-label';
+// or via entry-point:
+import DateLabel from '@atlaskit/date-label/date-label';
+
+// Neutral (default)
+<DateLabel label="29 Jul 2026" />
+
+// Warning — for upcoming/near-due dates
+<DateLabel label="29 Jul 2026" appearance="warning" />
+
+// Danger — for overdue dates
+<DateLabel label="29 Jul 2026" appearance="danger" />
+
+// Without icon
+<DateLabel label="29 Jul 2026" hasIconBefore={false} />
+
+// Spacious — 32px height, body font size
+<DateLabel label="29 Jul 2026" isSpacious />
+
+// Custom max width
+<DateLabel label="29 Jul 2026" maxWidth={120} />
+```
+
+### DateLabelDropdownTrigger
+
+Date label dropdown trigger is an interactive date label that opens a menu for date selection.
+
+```tsx
+import { DateLabelDropdownTrigger } from '@atlaskit/date-label';
+// or via entry-point:
+import { DateLabelDropdownTrigger } from '@atlaskit/date-label/date-label-dropdown-trigger';
+
+<DateLabelDropdownTrigger
+  label="29 Jul 2026"
+  appearance="neutral"
+  onClick={() => setOpen(true)}
+  aria-expanded={isOpen}
+  aria-haspopup="dialog"
+/>
+
+// Spacious variant
+<DateLabelDropdownTrigger label="29 Jul 2026" isSpacious />
+```
+
+### Importing types
+
+```tsx
+import type { DateLabelProps, DateLabelAppearance } from '@atlaskit/date-label';
+import type {
+	DateLabelDropdownTriggerProps,
+	DateLabelDropdownTriggerAppearance,
+} from '@atlaskit/date-label';
+
+// or via the types entry-point:
+import type {
+	DateLabelAppearance,
+	DateLabelDropdownTriggerAppearance,
+} from '@atlaskit/date-label/types';
+```
+
+## Appearances
+
+| Appearance | Border colour                     | Text colour          | Icon               |
+| ---------- | --------------------------------- | -------------------- | ------------------ |
+| `neutral`  | `color.border.accent.gray.subtle` | `color.text`         | CalendarIcon       |
+| `warning`  | `color.border.warning.subtle`     | `color.text.warning` | ClockIcon          |
+| `danger`   | `color.border.danger.subtle`      | `color.text.danger`  | WarningOutlineIcon |
+
+## Entry-points
+
+| Entry-point                                        | Exports                                                                                                     |
+| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `@atlaskit/date-label`                             | `DateLabel` (default), `DateLabelDropdownTrigger`, all types                                                |
+| `@atlaskit/date-label/date-label`                  | `DateLabel` (default), `DateLabelProps`, `DateLabelAppearance`                                              |
+| `@atlaskit/date-label/date-label-dropdown-trigger` | `DateLabelDropdownTrigger` (default), `DateLabelDropdownTriggerProps`, `DateLabelDropdownTriggerAppearance` |
+| `@atlaskit/date-label/types`                       | All exported types                                                                                          |
+
+## Props
+
+### DateLabel
+
+| Prop            | Type                  | Default     | Description                                                                                                                |
+| --------------- | --------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `label`         | `string`              | required    | The text to display                                                                                                        |
+| `appearance`    | `DateLabelAppearance` | `'neutral'` | Controls border, text, and icon colour                                                                                     |
+| `hasIconBefore` | `boolean`             | `true`      | Shows a contextual icon before the label                                                                                   |
+| `iconLabel`     | `string`              | —           | Accessible label for the icon. Defaults to `'Date'`, `'Warning'`, `'Danger'` per appearance. Pass `''` to make decorative. |
+| `isSpacious`    | `boolean`             | `false`     | Increases height to 32px and uses body font                                                                                |
+| `maxWidth`      | `number \| string`    | `180`       | Max width in px (number) or any CSS value (string)                                                                         |
+| `testId`        | `string`              | —           | `data-testid` for automated tests                                                                                          |
+
+### DateLabelDropdownTrigger
+
+| Prop            | Type                                   | Default     | Description                                                                                                                |
+| --------------- | -------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `label`         | `string`                               | required    | The text to display                                                                                                        |
+| `appearance`    | `DateLabelDropdownTriggerAppearance`   | `'neutral'` | Controls border, text, and icon colour                                                                                     |
+| `hasIconBefore` | `boolean`                              | `true`      | Shows a contextual icon before the label                                                                                   |
+| `iconLabel`     | `string`                               | —           | Accessible label for the icon. Defaults to `'Date'`, `'Warning'`, `'Danger'` per appearance. Pass `''` to make decorative. |
+| `isLoading`     | `boolean`                              | `false`     | Shows a loading spinner overlay and disables interaction                                                                   |
+| `isSelected`    | `boolean`                              | `false`     | Applies selected background and text colour                                                                                |
+| `isSpacious`    | `boolean`                              | `false`     | Increases height to 32px and uses body font                                                                                |
+| `maxWidth`      | `number \| string`                     | `200`       | Max width in px (number) or any CSS value (string)                                                                         |
+| `onClick`       | `MouseEventHandler<HTMLButtonElement>` | —           | Click handler                                                                                                              |
+| `aria-controls` | `string`                               | —           | ID of the controlled popup element                                                                                         |
+| `aria-expanded` | `boolean`                              | —           | Whether the popup is open                                                                                                  |
+| `aria-haspopup` | `boolean \| 'dialog'`                  | —           | Type of popup this triggers                                                                                                |
+| `aria-label`    | `string`                               | —           | Accessible label (falls back to `label` text)                                                                              |
+| `testId`        | `string`                               | —           | `data-testid` for automated tests                                                                                          |
+
+Detailed docs and example usage can be found
+[here](https://atlaskit.atlassian.com/packages/design-system/date-label).

package/constellation/date-label-dropdown-trigger/code.mdx

@@ -0,0 +1,13 @@
+---
+order: 1
+title: Date label dropdown trigger
+description: Date label dropdown trigger is an interactive date label that opens a dropdown for date selection.
+props:
+  packageName: '@atlaskit/date-label'
+  exports:
+    - DateLabelDropdownTriggerProps
+---
+
+## Props
+
+<TSMorphProps packageName="@atlaskit/date-label" exportName="DateLabelDropdownTriggerProps" />

package/constellation/date-label-dropdown-trigger/examples.mdx

@@ -0,0 +1,48 @@
+---
+order: 0
+title: Date label dropdown trigger
+description:
+  Date label dropdown trigger is an interactive date label that opens a dropdown for date selection.
+---
+
+import DateLabelDropdownTriggerExample from '../../examples/constellation/date-label-dropdown-trigger';
+import DateLabelDropdownTriggerSpacious from '../../examples/constellation/date-label-dropdown-trigger-spacious';
+import DateLabelDropdownTriggerSelected from '../../examples/constellation/date-label-dropdown-trigger-selected';
+import DateLabelDropdownTriggerLoading from '../../examples/constellation/date-label-dropdown-trigger-loading';
+import DateLabelDropdownTriggerNoIcon from '../../examples/constellation/date-label-dropdown-trigger-no-icon';
+
+## Basic
+
+Use `DateLabelDropdownTrigger` when the date label should open a picker or menu. It renders as a
+`<button>` with hover, pressed, and focus-ring states, and a chevron icon on the right to signal
+interactivity.
+
+<Example Component={DateLabelDropdownTriggerExample} packageName="@atlaskit/date-label" />
+
+## Spacious
+
+Use `isSpacious` for more spacious layouts such as forms or detail views. This increases the height
+to 32px and uses the body font size.
+
+<Example Component={DateLabelDropdownTriggerSpacious} packageName="@atlaskit/date-label" />
+
+## Selected
+
+Use `isSelected` to indicate that the dropdown is currently open. This applies a pressed background
+to the trigger. Pair with `aria-expanded` to communicate the open state to assistive technology.
+
+<Example Component={DateLabelDropdownTriggerSelected} packageName="@atlaskit/date-label" />
+
+## Loading
+
+Use `isLoading` to indicate that an async operation is in progress, such as saving a date selection.
+When loading, the chevron is replaced with a spinner, clicks are suppressed, and `aria-busy` is set
+on the button.
+
+<Example Component={DateLabelDropdownTriggerLoading} packageName="@atlaskit/date-label" />
+
+## Without icon
+
+Set `hasIconBefore={false}` to hide the leading contextual icon.
+
+<Example Component={DateLabelDropdownTriggerNoIcon} packageName="@atlaskit/date-label" />

package/constellation/date-label-dropdown-trigger/usage.mdx

@@ -0,0 +1,176 @@
+---
+order: 2
+title: Date label dropdown trigger
+description:
+  Date label dropdown trigger is an interactive date label that opens a dropdown for date selection.
+---
+
+import Image from '@atlaskit/image';
+
+import dateLabelDropdownAnatomyLight from './images/datelabel-dropdown-anatomy-light.png';
+import dateLabelDropdownAnatomyDark from './images/datelabel-dropdown-anatomy-dark.png';
+import dateLabelDropdownDo1Light from './images/datelabel-dropdown-do-1-light.png';
+import dateLabelDropdownDo1Dark from './images/datelabel-dropdown-do-1-dark.png';
+import dateLabelDropdownDont1Light from './images/datelabel-dropdown-dont-1-light.png';
+import dateLabelDropdownDont1Dark from './images/datelabel-dropdown-dont-1-dark.png';
+import dateLabelDropdownDo2Light from './images/datelabel-dropdown-do-2-light.png';
+import dateLabelDropdownDo2Dark from './images/datelabel-dropdown-do-2-dark.png';
+import dateLabelDropdownDont2Light from './images/datelabel-dropdown-dont-2-light.png';
+import dateLabelDropdownDont2Dark from './images/datelabel-dropdown-dont-2-dark.png';
+import dateLabelDropdownDo3Light from './images/datelabel-dropdown-do-3-light.png';
+import dateLabelDropdownDo3Dark from './images/datelabel-dropdown-do-3-dark.png';
+import dateLabelDropdownDont3Light from './images/datelabel-dropdown-dont-3-light.png';
+import dateLabelDropdownDont3Dark from './images/datelabel-dropdown-dont-3-dark.png';
+import dateLabelDropdownDo4Light from './images/datelabel-dropdown-do-4-light.png';
+import dateLabelDropdownDo4Dark from './images/datelabel-dropdown-do-4-dark.png';
+import dateLabelDropdownDont4Light from './images/datelabel-dropdown-dont-4-light.png';
+import dateLabelDropdownDont4Dark from './images/datelabel-dropdown-dont-4-dark.png';
+
+## Usage
+
+Date label dropdown trigger displays dates and provides a trigger to open a dropdown for date
+selection. They differ from date labels in that they contain interactivity to trigger a dropdown,
+making it ideal for workflows that require date picking.
+
+## Parts
+
+<Image
+	src={dateLabelDropdownAnatomyLight}
+	srcDark={dateLabelDropdownAnatomyDark}
+	alt="The anatomy of the date label dropdown trigger component, showing three parts: an optional icon, a label, and a dropdown chevron icon"
+/>
+
+1. **Label:** Text displaying the date.
+2. **Icon (optional):** An icon that corresponds to the appearance. Each appearance has a designated
+   icon that displays automatically when enabled.
+3. **Dropdown icon:** Indicates that this date label can be selected to open a dropdown.
+
+## Best practices
+
+### Use date label dropdown trigger for date selection
+
+Date label dropdown trigger should only open a dropdown to allow for switching between dates.
+
+<DoDontGrid>
+	<DoDont
+		type="do"
+		image={{
+			url: dateLabelDropdownDo1Light,
+			urlDarkMode: dateLabelDropdownDo1Dark,
+			alt: 'Use date label dropdown trigger to open a dropdown for date selection.',
+		}}
+	>
+		Use date label dropdown trigger to open a dropdown for date selection.
+	</DoDont>
+	<DoDont
+		type="dont"
+		image={{
+			url: dateLabelDropdownDont1Light,
+			urlDarkMode: dateLabelDropdownDont1Dark,
+			alt: "Don't use date label dropdown trigger to open menus unrelated to date selection.",
+		}}
+	>
+		Don't use date label dropdown trigger to open menus unrelated to date selection.
+	</DoDont>
+</DoDontGrid>
+
+### Use the spacing property appropriately
+
+Use the spacing prop to adjust the date label dropdown trigger so its size aligns with surrounding
+elements, such as when it appears alongside other buttons.
+
+<DoDontGrid>
+	<DoDont
+		type="do"
+		image={{
+			url: dateLabelDropdownDo2Light,
+			urlDarkMode: dateLabelDropdownDo2Dark,
+			alt: 'Use the spacious variant when the date label dropdown trigger appears alongside other buttons.',
+		}}
+	>
+		Use the spacious variant when the date label dropdown trigger appears alongside other buttons.
+	</DoDont>
+	<DoDont
+		type="dont"
+		image={{
+			url: dateLabelDropdownDont2Light,
+			urlDarkMode: dateLabelDropdownDont2Dark,
+			alt: "Don't use the default size alongside larger interactive elements.",
+		}}
+	>
+		Don't use the default size alongside larger interactive elements.
+	</DoDont>
+</DoDontGrid>
+
+### Use date time picker for date entry in forms
+
+Date label dropdown trigger is designed to sit alongside other labels like lozenge and tag. It is
+not a form input. For date entry in forms, use a date time picker.
+
+<DoDontGrid>
+	<DoDont
+		type="do"
+		image={{
+			url: dateLabelDropdownDo3Light,
+			urlDarkMode: dateLabelDropdownDo3Dark,
+			alt: 'Use date label dropdown trigger alongside other labels in structured UI contexts.',
+		}}
+	>
+		Use date label dropdown trigger alongside other labels in structured UI contexts.
+	</DoDont>
+	<DoDont
+		type="dont"
+		image={{
+			url: dateLabelDropdownDont3Light,
+			urlDarkMode: dateLabelDropdownDont3Dark,
+			alt: "Don't use date label dropdown trigger as a form input for date entry.",
+		}}
+	>
+		Don't use date label dropdown trigger as a form input for date entry.
+	</DoDont>
+</DoDontGrid>
+
+## Accessibility
+
+### Use icons that carry appropriate meaning for semantic states
+
+Date labels come with designated icons for each of its semantic states. These icons are essential
+for accessibility. Without them, users must rely solely on color to distinguish states, which may
+not be perceivable to everyone.
+
+<DoDontGrid>
+	<DoDont
+		type="do"
+		image={{
+			url: dateLabelDropdownDo4Light,
+			urlDarkMode: dateLabelDropdownDo4Dark,
+			alt: 'Use the assigned icons for semantic appearances like an overdue date.',
+		}}
+	>
+		Use the assigned icons for semantic appearances like an overdue date.
+	</DoDont>
+	<DoDont
+		type="dont"
+		image={{
+			url: dateLabelDropdownDont4Light,
+			urlDarkMode: dateLabelDropdownDont4Dark,
+			alt: "Don't remove icons for semantic appearances or use icons that don't carry appropriate meaning.",
+		}}
+	>
+		Don't remove icons for semantic appearances or use icons that don't carry appropriate meaning.
+	</DoDont>
+</DoDontGrid>
+
+## Data Center apps
+
+For all new features, we recommend using Atlassian Design System and other
+[Atlaskit components](https://atlaskit.atlassian.com/). For existing code, you can continue to use
+[Atlassian User Interface (AUI)](https://aui.atlassian.com/).
+
+## Related
+
+- For status information, use a [lozenge](/components/lozenge/lozenge).
+- For lozenges requiring dropdown interactivity, use
+  [lozenge dropdown trigger](/components/lozenge/lozenge-dropdown-trigger).
+- For counts or tallies, use a [badge](/components/badge/badge).
+- To visually label content such as categories and attributes, use a [tag](/components/tag/tag).

package/constellation/index/examples.mdx

@@ -0,0 +1,66 @@
+---
+title: Date label
+description:
+  Date label is a non-interactive label that displays a date and optionally, visually communicates
+  its status.
+order: 0
+---
+
+import DateLabelNeutral from '../../examples/constellation/date-label-neutral';
+import DateLabelWarning from '../../examples/constellation/date-label-warning';
+import DateLabelDanger from '../../examples/constellation/date-label-danger';
+import DateLabelNoIcon from '../../examples/constellation/date-label-no-icon';
+import DateLabelMaxWidth from '../../examples/constellation/date-label-max-width';
+import DateLabelSpacious from '../../examples/constellation/date-label-spacious';
+
+## Appearance
+
+Date labels use three appearances to communicate the status of a date at a glance.
+
+### Neutral
+
+Use `neutral` for standard dates with no urgency. For example, a future date that is well within the
+deadline.
+
+<Example Component={DateLabelNeutral} packageName="@atlaskit/date-label" />
+
+### Warning
+
+Use `warning` for dates that are approaching and require attention. For example, a due date that is
+coming up soon.
+
+<Example Component={DateLabelWarning} packageName="@atlaskit/date-label" />
+
+### Danger
+
+Use `danger` for dates that are overdue or past the deadline.
+
+<Example Component={DateLabelDanger} packageName="@atlaskit/date-label" />
+
+## Icon
+
+By default, each appearance shows a contextual icon before the label:
+
+- `neutral` → calendar icon
+- `warning` → clock icon
+- `danger` → warning icon
+
+Set `hasIconBefore={false}` to hide the icon.
+
+<Example Component={DateLabelNoIcon} packageName="@atlaskit/date-label" />
+
+## Spacious
+
+Use `isSpacious` for more spacious layouts such as forms or detail views. This increases the height
+to 32px, uses `radius.medium` for the border radius, and switches the label to the body font size.
+
+<Example Component={DateLabelSpacious} packageName="@atlaskit/date-label" />
+
+## Max width
+
+When the label text exceeds the maximum width it will be truncated with an ellipsis. The default
+maximum width is `180px`. Use the `maxWidth` prop to customise this.
+
+Avoid truncation wherever possible by using concise date strings.
+
+<Example Component={DateLabelMaxWidth} packageName="@atlaskit/date-label" />

package/constellation/index/props.mdx

@@ -0,0 +1,14 @@
+---
+title: Date label
+description:
+  Date label is a non-interactive label that displays a date and optionally, visually communicates
+  its status.
+props:
+  packageName: '@atlaskit/date-label'
+  exports:
+    - DateLabelProps
+---
+
+## Props
+
+<TSMorphProps exportName="DateLabelProps" packageName="@atlaskit/date-label" />