vueless 1.5.1-beta.2 → 1.5.1-beta.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vueless",
-  "version": "1.5.1-beta.2",
+  "version": "1.5.1-beta.3",
   "description": "Vue Styleless UI Component Library, powered by Tailwind CSS.",
   "author": "Johnny Grid <hello@vueless.com> (https://vueless.com)",
   "homepage": "https://vueless.com",

package/ui.form-calendar/UCalendar.vue

@@ -54,6 +54,7 @@ const props = withDefaults(defineProps<Props<TModelValue>>(), {
   modelValue: undefined,
   minDate: undefined,
   maxDate: undefined,
+  dayClasses: undefined,
 });
 
 const emit = defineEmits([
@@ -918,6 +919,7 @@ const {
       :date-format="actualDateFormat"
       :locale="locale"
       :config="config"
+      :day-classes="dayClasses"
       :is-arrow-key-dirty="isArrowKeyDirty"
       :data-test="getDataTest('day-view')"
       @input="onInputDate"

package/ui.form-calendar/UCalendarDayView.vue

@@ -232,6 +232,10 @@ function onMouseleaveDayView() {
   }
 }
 
+function getDayCustomClasses(day: Date) {
+  return props.dayClasses?.(day);
+}
+
 /**
  * Get element / nested component attributes for each config token ✨
  * Applies: `class`, `config`, redefined default `props` and dev `vl-...` attributes.
@@ -279,6 +283,7 @@ defineExpose({
           size="md"
           square
           v-bind="selectedDayAttrs"
+          :class="getDayCustomClasses(day)"
           :disabled="dateIsOutOfRange(day, minDate, maxDate, locale, dateFormat)"
           :label="formatDate(day, 'j', locale)"
           @mousedown.prevent.capture
@@ -294,6 +299,7 @@ defineExpose({
           size="md"
           square
           v-bind="selectedDayAttrs"
+          :class="getDayCustomClasses(day)"
           :disabled="dateIsOutOfRange(day, minDate, maxDate, locale, dateFormat)"
           :label="formatDate(day, 'j', locale)"
           @mousedown.prevent.capture
@@ -311,6 +317,7 @@ defineExpose({
           size="md"
           square
           v-bind="firstDayInRangeAttrs"
+          :class="getDayCustomClasses(day)"
           :disabled="dateIsOutOfRange(day, minDate, maxDate, locale, dateFormat)"
           :label="formatDate(day, 'j', locale)"
           @mousedown.prevent.capture
@@ -328,6 +335,7 @@ defineExpose({
           size="md"
           square
           v-bind="lastDayInRangeAttrs"
+          :class="getDayCustomClasses(day)"
           :disabled="dateIsOutOfRange(day, minDate, maxDate, locale, dateFormat)"
           :label="formatDate(day, 'j', locale)"
           @mousedown.prevent.capture
@@ -343,6 +351,7 @@ defineExpose({
           size="md"
           square
           v-bind="anotherMonthFirstDayInRangeAttrs"
+          :class="getDayCustomClasses(day)"
           :disabled="dateIsOutOfRange(day, minDate, maxDate, locale, dateFormat)"
           :label="formatDate(day, 'j', locale)"
           @mousedown.prevent.capture
@@ -358,6 +367,7 @@ defineExpose({
           size="md"
           square
           v-bind="anotherMonthLastDayInRangeAttrs"
+          :class="getDayCustomClasses(day)"
           :disabled="dateIsOutOfRange(day, minDate, maxDate, locale, dateFormat)"
           :label="formatDate(day, 'j', locale)"
           @mousedown.prevent.capture
@@ -373,6 +383,7 @@ defineExpose({
           size="md"
           square
           v-bind="lastDayInRangeAttrs"
+          :class="getDayCustomClasses(day)"
           :disabled="dateIsOutOfRange(day, minDate, maxDate, locale, dateFormat)"
           :label="formatDate(day, 'j', locale)"
           @mousedown.prevent.capture
@@ -391,6 +402,7 @@ defineExpose({
           size="md"
           square
           v-bind="anotherMonthDayInRangeAttrs"
+          :class="getDayCustomClasses(day)"
           :disabled="dateIsOutOfRange(day, minDate, maxDate, locale, dateFormat)"
           :label="formatDate(day, 'j', locale)"
           @mousedown.prevent.capture
@@ -409,6 +421,7 @@ defineExpose({
           size="md"
           square
           v-bind="currentDayInRangeAttrs"
+          :class="getDayCustomClasses(day)"
           :disabled="dateIsOutOfRange(day, minDate, maxDate, locale, dateFormat)"
           :label="formatDate(day, 'j', locale)"
           @mousedown.prevent.capture
@@ -424,6 +437,7 @@ defineExpose({
           size="md"
           square
           v-bind="dayInRangeAttrs"
+          :class="getDayCustomClasses(day)"
           :disabled="dateIsOutOfRange(day, minDate, maxDate, locale, dateFormat)"
           :label="formatDate(day, 'j', locale)"
           @mousedown.prevent.capture
@@ -439,6 +453,7 @@ defineExpose({
           size="md"
           square
           v-bind="currentDayAttrs"
+          :class="getDayCustomClasses(day)"
           :disabled="dateIsOutOfRange(day, minDate, maxDate, locale, dateFormat)"
           :label="formatDate(day, 'j', locale)"
           @mousedown.prevent.capture
@@ -454,6 +469,7 @@ defineExpose({
           size="md"
           square
           v-bind="activeDayAttrs"
+          :class="getDayCustomClasses(day)"
           :disabled="dateIsOutOfRange(day, minDate, maxDate, locale, dateFormat)"
           :label="formatDate(day, 'j', locale)"
           @mousedown.prevent.capture
@@ -469,6 +485,7 @@ defineExpose({
           size="md"
           square
           v-bind="anotherMonthDayAttrs"
+          :class="getDayCustomClasses(day)"
           :disabled="dateIsOutOfRange(day, minDate, maxDate, locale, dateFormat)"
           :label="formatDate(day, 'j', locale)"
           @mousedown.prevent.capture
@@ -484,6 +501,7 @@ defineExpose({
           size="md"
           square
           v-bind="dayAttrs"
+          :class="getDayCustomClasses(day)"
           :disabled="dateIsOutOfRange(day, minDate, maxDate, locale, dateFormat)"
           :label="formatDate(day, 'j', locale)"
           @mousedown.prevent.capture

package/ui.form-calendar/storybook/stories.ts

@@ -147,3 +147,29 @@ MinMax.parameters = {
     },
   },
 };
+
+export const DayClasses = DefaultTemplate.bind({});
+DayClasses.args = {
+  dayClasses: (day: Date) => {
+    return [5, 12, 19].includes(day.getDate()) ? "bg-success" : "";
+  },
+};
+DayClasses.parameters = {
+  docs: {
+    description: {
+      story:
+        // eslint-disable-next-line vue/max-len
+        "Use the `dayClasses` prop to apply extra CSS classes to individual day cells, e.g. to highlight dates by status.",
+    },
+    source: {
+      code: `
+        <UCalendar
+          v-model="args.modelValue"
+          :day-classes="(day) => ([5, 12, 19].includes(day.getDate()) ? 'bg-success' : '')"
+        />
+
+        <UText color="neutral" class="mt-4">{{ args.modelValue }}</UText>
+      `,
+    },
+  },
+};

package/ui.form-calendar/tests/UCalendar.test.ts

@@ -295,6 +295,19 @@ describe("UCalendar.vue", () => {
       expect(updatedValue.to).toMatch(dateFormatRegex);
     });
 
+    it("Day Classes – passes dayClasses to UCalendarDayView", () => {
+      const dayClasses = (day: Date) => (day.getDate() === 15 ? "bg-mint-highlight" : "");
+
+      const component = mount(UCalendar, {
+        props: {
+          modelValue: null,
+          dayClasses,
+        },
+      });
+
+      expect(component.findComponent(DayView).props("dayClasses")).toBe(dayClasses);
+    });
+
     it("Tabindex – sets tabindex attribute on wrapper", () => {
       const tabindex = 5;
 

package/ui.form-calendar/tests/UCalendarDayView.test.ts

@@ -386,6 +386,39 @@ describe("UCalendarDayView.vue", () => {
     });
   });
 
+  describe("Day Classes Prop", () => {
+    it("applies function-based dayClasses only to the matching day", () => {
+      const component = mount(UCalendarDayView, {
+        props: {
+          ...defaultProps,
+          selectedDate: null,
+          dayClasses: (day: Date) => (day.getDate() === 10 ? "bg-mint-highlight" : ""),
+        },
+      });
+
+      const dayButtons = component.findAll('[vl-key="day"]');
+      const targetDay = dayButtons.find((button) => button.text() === "10");
+      const otherDay = dayButtons.find((button) => button.text() === "12");
+
+      expect(targetDay?.classes()).toContain("bg-mint-highlight");
+      expect(otherDay?.classes()).not.toContain("bg-mint-highlight");
+    });
+
+    it("renders regular day cells without error when dayClasses prop is not provided", () => {
+      const component = mount(UCalendarDayView, {
+        props: {
+          ...defaultProps,
+          selectedDate: null,
+        },
+      });
+
+      const regularDay = component.find('[vl-key="day"]');
+
+      expect(regularDay.exists()).toBe(true);
+      expect(regularDay.classes()).not.toContain("bg-mint-highlight");
+    });
+  });
+
   describe("Exposed Properties", () => {
     it("exposes days computed property", () => {
       const component = mount(UCalendarDayView, {

package/ui.form-calendar/types.ts

@@ -72,6 +72,11 @@ export interface Props<TModelValue extends DateValue> {
    */
   maxDate?: Date | string;
 
+  /**
+   * Extra CSS classes to apply to each day cell, on top of the built-in state classes.
+   */
+  dayClasses?: (day: Date) => string;
+
   /**
    * Component config object.
    */
@@ -93,5 +98,6 @@ export interface UCalendarViewProps {
   isArrowKeyDirty: boolean;
   maxDate?: Date | string;
   minDate?: Date | string;
+  dayClasses?: (day: Date) => string;
   config: Config;
 }

package/ui.form-date-picker/UDatePicker.vue

@@ -34,6 +34,7 @@ const props = withDefaults(defineProps<Props<TModelValue>>(), {
   modelValue: undefined,
   minDate: undefined,
   maxDate: undefined,
+  dayClasses: undefined,
   placeholder: "",
   label: "",
 });
@@ -364,6 +365,7 @@ watchEffect(() => {
         :user-date-time-format="userDateTimeFormat"
         :max-date="maxDate"
         :min-date="minDate"
+        :day-classes="dayClasses"
         v-bind="datepickerCalendarAttrs"
         :data-test="getDataTest('calendar')"
         @keydown.esc="deactivate"

package/ui.form-date-picker/storybook/stories.ts

@@ -454,3 +454,32 @@ Slots.parameters = {
     },
   },
 };
+
+export const DayClasses = DefaultTemplate.bind({});
+DayClasses.args = {
+  modelValue: dateValue,
+  dayClasses: (day: Date) => {
+    return [5, 12, 19].includes(day.getDate()) ? "bg-success" : "";
+  },
+};
+DayClasses.parameters = {
+  docs: {
+    description: {
+      story:
+        // eslint-disable-next-line vue/max-len
+        "Use the `dayClasses` prop to apply extra CSS classes to individual day cells, e.g. to highlight dates by status.",
+    },
+    source: {
+      code: `
+        <UDatePicker
+          v-model="args.modelValue"
+          label="Select a date"
+          :day-classes="(day) => ([5, 12, 19].includes(day.getDate()) ? 'bg-success' : '')"
+          class="max-w-96"
+        />
+
+        <UText color="neutral" class="mt-4">{{ args.modelValue }}</UText>
+      `,
+    },
+  },
+};

package/ui.form-date-picker/tests/UDatePicker.test.ts

@@ -284,6 +284,19 @@ describe("UDatePicker.vue", () => {
       expect(component.findComponent({ name: "UCalendar" }).props("maxDate")).toBe(maxDate);
     });
 
+    it("Day Classes – passes dayClasses to UCalendar", () => {
+      const dayClasses = (day: Date) => (day.getDate() === 15 ? "bg-mint-highlight" : "");
+
+      const component = mount(UDatePicker, {
+        props: {
+          modelValue: new Date(),
+          dayClasses,
+        },
+      });
+
+      expect(component.findComponent({ name: "UCalendar" }).props("dayClasses")).toBe(dayClasses);
+    });
+
     it("Id – sets id attribute on input", () => {
       const idValue = "date-picker-id";
 

package/ui.form-date-picker/types.ts

@@ -103,6 +103,11 @@ export interface Props<TModelValue> {
    */
   rightIcon?: string;
 
+  /**
+   * Extra CSS classes to apply to each day cell, on top of the built-in state classes.
+   */
+  dayClasses?: (day: Date) => string;
+
   /**
    * Unique element id.
    */

package/ui.form-date-picker-range/UDatePickerRange.vue

@@ -73,9 +73,12 @@ defineOptions({ inheritAttrs: false });
 const props = withDefaults(defineProps<Props<TModelValue>>(), {
   ...getDefaults<Props<TModelValue>, Config>(defaultConfig, COMPONENT_NAME),
   customRangeButton: () => ({ range: { from: null, to: null } }),
+  periods: () =>
+    getDefaults<Props<TModelValue>, Config>(defaultConfig, COMPONENT_NAME).periods || [],
   modelValue: undefined,
   minDate: undefined,
   maxDate: undefined,
+  dayClasses: undefined,
   placeholder: "",
   label: "",
 });
@@ -129,7 +132,21 @@ const activeDate: Ref<string | Date | null> = ref(
     ? parseDate<SortedLocale>(props.modelValue.from, props.dateFormat, locale.value)
     : new Date(),
 );
-const period = ref(Period.OwnRange);
+let isInvalidPeriodsWarned = false;
+const allowedPeriods = computed(() => getAllowedPeriods());
+const isPeriodSwitchShown = computed(() => {
+  const hasCustomRange = Boolean(
+    props.customRangeButton.range.from && props.customRangeButton.range.to,
+  );
+  const periodButtonCount = allowedPeriods.value.filter((type) => type !== Period.Custom).length;
+
+  return periodButtonCount + Number(hasCustomRange) > 1;
+});
+const rawPeriod = ref(Period.OwnRange);
+const period = computed({
+  get: () => getAllowedPeriod(rawPeriod.value),
+  set: (value: Period) => (rawPeriod.value = value),
+});
 const rangeStart = ref("");
 const rangeEnd = ref("");
 const inputRangeFromError = ref("");
@@ -319,6 +336,29 @@ function deactivate() {
   isShownMenu.value = false;
 }
 
+function getAllowedPeriods(): readonly Period[] {
+  const allPeriods = Object.values(Period);
+  const validPeriods = allPeriods.filter((type) => props.periods.includes(type));
+
+  if (validPeriods.length) return validPeriods;
+
+  if (import.meta.env.DEV && !isInvalidPeriodsWarned) {
+    // eslint-disable-next-line no-console
+    console.warn(`[${COMPONENT_NAME}] No valid "periods" provided, falling back to all periods.`);
+    isInvalidPeriodsWarned = true;
+  }
+
+  return allPeriods;
+}
+
+function getAllowedPeriod(detectedPeriod: Period): Period {
+  if (detectedPeriod === Period.Custom || allowedPeriods.value.includes(detectedPeriod)) {
+    return detectedPeriod;
+  }
+
+  return allowedPeriods.value.includes(Period.OwnRange) ? Period.OwnRange : allowedPeriods.value[0];
+}
+
 setDefaultPeriodForButton();
 
 function setDefaultPeriodForButton() {
@@ -404,16 +444,12 @@ function shiftRangeNext(to: Date, from: Date, daysDifference: number) {
     return;
   }
 
-  let nextDate = periodDateList.value.find(
-    (item) => localValue.value.to && item.endRange > localValue.value.to,
-  );
+  let nextDate = periodDateList.value.find((item) => item.startRange > from);
 
   if (!nextDate) {
     onClickShiftDatesList(ShiftAction.Next);
 
-    nextDate = periodDateList.value.find(
-      (item) => localValue.value.to && item.endRange > localValue.value.to,
-    );
+    nextDate = periodDateList.value.find((item) => item.startRange > from);
   }
 
   if (nextDate && isDatePeriodOutOfRange(nextDate)) return;
@@ -468,8 +504,19 @@ function shiftRangePrev(to: Date, from: Date, daysDifference: number) {
   }
 }
 
+function getPeriodDateList(date: Date): DatePeriodRange[] {
+  if (isPeriod.value.week) return getWeekDateList(date, locale.value.months.shorthand);
+  if (isPeriod.value.month) return getMonthsDateList(date, locale.value.months.longhand);
+  if (isPeriod.value.quarter) return getQuartersDateList(date, locale.value.quarter);
+  if (isPeriod.value.year) return getYearDateList(date);
+
+  return [];
+}
+
 function onClickShiftRange(action: ShiftActions) {
-  if (isPeriod.value.custom) {
+  const isLeavingCustom = isPeriod.value.custom;
+
+  if (isLeavingCustom) {
     period.value = Period.OwnRange;
   }
 
@@ -487,6 +534,10 @@ function onClickShiftRange(action: ShiftActions) {
   if (!from) return;
   to = to || addDays(from, 1);
 
+  if (isLeavingCustom && !isPeriod.value.ownRange) {
+    periodDateList.value = getPeriodDateList(from);
+  }
+
   const daysDifference = Math.ceil(Math.abs(getDatesDifference(from, to)) / millisecondsPerDay);
 
   action === ShiftAction.Next
@@ -568,6 +619,7 @@ const mutatedProps = computed(() => ({
   quarter: isPeriod.value.quarter,
   year: isPeriod.value.year,
   customRangeButtonDescription: Boolean(props.customRangeButton.description),
+  periodSwitch: isPeriodSwitchShown.value,
 }));
 
 const {
@@ -730,6 +782,8 @@ watchEffect(() => {
           v-model:period="period"
           :config="config"
           :is-period="isPeriod"
+          :allowed-periods="allowedPeriods"
+          :is-period-switch-shown="isPeriodSwitchShown"
           :custom-range-button="customRangeButton"
           :locale="locale"
           :date-format="dateFormat"
@@ -781,6 +835,7 @@ watchEffect(() => {
           :min-date="minDate"
           :max-date="maxDate"
           :date-format="dateFormat"
+          :day-classes="dayClasses"
           v-bind="datepickerCalendarAttrs as KeyAttrsWithConfig<UCalendarConfig>"
           range
           :data-test="getDataTest('calendar')"

package/ui.form-date-picker-range/UDatePickerRangePeriodMenu.vue

@@ -36,12 +36,20 @@ const isDatePeriodOutOfRange = inject<IsDatePeriodOutOfRange | null>(
   null,
 );
 
-const periods = computed(() => [
-  { name: Period.Week, title: props.locale.week },
-  { name: Period.Month, title: props.locale.month },
-  { name: Period.Quarter, title: props.locale.quarter },
-  { name: Period.Year, title: props.locale.year },
-]);
+const periods = computed(() =>
+  [
+    { name: Period.Week, title: props.locale.week },
+    { name: Period.Month, title: props.locale.month },
+    { name: Period.Quarter, title: props.locale.quarter },
+    { name: Period.Year, title: props.locale.year },
+  ].filter(({ name }) => props.allowedPeriods.includes(name)),
+);
+
+const isOwnRangeAllowed = computed(() => props.allowedPeriods.includes(Period.OwnRange));
+
+const hasCustomRange = computed(() =>
+  Boolean(props.customRangeButton.range.from && props.customRangeButton.range.to),
+);
 
 const rangeSwitchTitle = computed(() => {
   if (props.isPeriod.month || props.isPeriod.quarter) {
@@ -148,7 +156,11 @@ function getDatePeriodState(date: DatePeriodRange) {
 </script>
 
 <template>
-  <div v-bind="attrs.periodRowAttrs.value" :data-test="getDataTest()">
+  <div
+    v-if="isPeriodSwitchShown && periods.length"
+    v-bind="attrs.periodRowAttrs.value"
+    :data-test="getDataTest()"
+  >
     <template v-for="periodButton in periods" :key="periodButton.name">
       <UButton
         v-if="periodButton.name !== period"
@@ -176,27 +188,12 @@ function getDatePeriodState(date: DatePeriodRange) {
     </template>
   </div>
 
-  <div v-bind="attrs.periodRowAttrs.value">
-    <UButton
-      v-if="customRangeButton.range.to && customRangeButton.range.from && Period.Custom !== period"
-      square
-      size="xs"
-      color="grayscale"
-      variant="soft"
-      :data-test="getDataTest('custom-range')"
-      v-bind="attrs.customRangeButtonAttrs.value"
-      @click="onClickCustomRangeButton"
-    >
-      {{ customRangeButton.label }}
-      <span
-        v-if="customRangeButton.description"
-        v-bind="attrs.customRangeDescriptionAttrs.value"
-        v-text="customRangeButton.description"
-      />
-    </UButton>
-
+  <div
+    v-if="isPeriodSwitchShown && (hasCustomRange || isOwnRangeAllowed)"
+    v-bind="attrs.periodRowAttrs.value"
+  >
     <UButton
-      v-if="customRangeButton.range.to && customRangeButton.range.from && Period.Custom === period"
+      v-if="hasCustomRange"
       square
       size="xs"
       color="grayscale"
@@ -214,7 +211,7 @@ function getDatePeriodState(date: DatePeriodRange) {
     </UButton>
 
     <UButton
-      v-if="Period.OwnRange !== period"
+      v-if="isOwnRangeAllowed && Period.OwnRange !== period"
       square
       size="xs"
       color="grayscale"
@@ -227,7 +224,7 @@ function getDatePeriodState(date: DatePeriodRange) {
     />
 
     <UButton
-      v-else
+      v-else-if="isOwnRangeAllowed"
       square
       size="xs"
       color="grayscale"

package/ui.form-date-picker-range/config.ts

@@ -60,7 +60,14 @@ export default /*tw*/ {
   periodRow: "mb-1 flex min-w-64 gap-1",
   periodButton: "{UButton} h-[3.125rem] w-full",
   periodButtonActive: "{>periodButton} bg-grayscale-accented/15!",
-  rangeSwitchWrapper: "flex items-center justify-between py-2",
+  rangeSwitchWrapper: {
+    base: "flex items-center justify-between py-2",
+    variants: {
+      periodSwitch: {
+        false: "pt-0",
+      },
+    },
+  },
   rangeSwitchButton: "{UButton}",
   rangeSwitchTitle: "font-medium text-medium",
   periodDateList: {
@@ -87,7 +94,14 @@ export default /*tw*/ {
     },
   },
   customRangeDescription: "",
-  rangeInputWrapper: "flex mt-4 group/range-input-wrapper",
+  rangeInputWrapper: {
+    base: "flex mt-4 group/range-input-wrapper",
+    variants: {
+      periodSwitch: {
+        false: "mt-2",
+      },
+    },
+  },
   rangeInput: {
     base: "{UInput}",
     inputLabel: {
@@ -211,6 +225,7 @@ export default /*tw*/ {
     dateFormat: undefined,
     maxDate: undefined,
     minDate: undefined,
+    periods: ["week", "month", "quarter", "year", "ownRange"],
     /* icons */
     calendarIcon: "calendar_month-fill",
     nextIcon: "keyboard_arrow_right",

package/ui.form-date-picker-range/storybook/stories.ts

@@ -225,6 +225,54 @@ OpenDirection.parameters = {
   },
 };
 
+export const Periods: StoryFn<DefaultUDatePickerRangeArgs> = (args) => ({
+  components: { UDatePickerRange, UCol, UText },
+  setup: () => ({ args }),
+  template: `
+    <UCol>
+      <UDatePickerRange
+        v-bind="args"
+        v-model="args.modelValue"
+        label="All periods (default)"
+        class="w-full max-w-96"
+      />
+      <UDatePickerRange
+        v-bind="args"
+        v-model="args.modelValue"
+        :periods="['month', 'quarter', 'year']"
+        label="Month, quarter, year"
+        class="w-full max-w-96"
+      />
+      <UDatePickerRange
+        v-bind="args"
+        v-model="args.modelValue"
+        :periods="['week', 'month']"
+        label="Week, month"
+        class="w-full max-w-96"
+      />
+      <UDatePickerRange
+        v-bind="args"
+        v-model="args.modelValue"
+        :periods="['ownRange']"
+        label="Own range only"
+        class="w-full max-w-96"
+      />
+    </UCol>
+
+    <UText color="neutral" class="mt-4">{{ args.modelValue }}</UText>
+  `,
+});
+Periods.parameters = {
+  docs: {
+    description: {
+      story: "Use the `periods` prop to limit which period types are available for selection.",
+    },
+    story: {
+      height: "800px",
+    },
+  },
+};
+
 export const DateFormat = DefaultTemplate.bind({});
 DateFormat.args = { variant: "input", dateFormat: "Y-m-d" };
 DateFormat.parameters = {
@@ -259,6 +307,35 @@ MinMax.parameters = {
   },
 };
 
+export const DayClasses = DefaultTemplate.bind({});
+DayClasses.args = {
+  modelValue: { from: fromDate, to: toDate },
+  dayClasses: (day: Date) => {
+    return [5, 12, 19].includes(day.getDate()) ? "bg-success" : "";
+  },
+};
+DayClasses.parameters = {
+  docs: {
+    description: {
+      story:
+        // eslint-disable-next-line vue/max-len
+        "Use the `dayClasses` prop to apply extra CSS classes to individual day cells, e.g. to highlight dates by status.",
+    },
+    source: {
+      code: `
+        <UDatePickerRange
+          v-model="args.modelValue"
+          label="Select date range"
+          :day-classes="(day) => ([5, 12, 19].includes(day.getDate()) ? 'bg-success' : '')"
+          class="w-full max-w-96"
+        />
+
+        <UText color="neutral" class="mt-4">{{ args.modelValue }}</UText>
+      `,
+    },
+  },
+};
+
 export const CustomRangeButton = DefaultTemplate.bind({});
 CustomRangeButton.args = {
   customRangeButton: {

package/ui.form-date-picker-range/tests/UDatePickerRange.test.ts

@@ -1,11 +1,12 @@
 import { mount } from "@vue/test-utils";
-import { describe, it, expect } from "vitest";
+import { describe, it, expect, vi } from "vitest";
 
 import UDatePickerRange from "../UDatePickerRange.vue";
 import UInput from "../../ui.form-input/UInput.vue";
 import ULabel from "../../ui.form-label/ULabel.vue";
 import UButton from "../../ui.button/UButton.vue";
 import UDatePickerRangePeriodMenu from "../UDatePickerRangePeriodMenu.vue";
+import { Period } from "../constants";
 
 import type { RangeDate } from "../../ui.form-calendar/types";
 
@@ -298,6 +299,24 @@ describe("UDatePickerRange.vue", () => {
       expect(component.props("maxDate")).toBe(maxDate);
     });
 
+    it("Day Classes – passes dayClasses to UCalendar", async () => {
+      const dayClasses = (day: Date) => (day.getDate() === 15 ? "bg-mint-highlight" : "");
+
+      const component = mount(UDatePickerRange, {
+        props: {
+          variant: "input",
+          dayClasses,
+          modelValue: { from: null, to: null },
+        },
+      });
+
+      const input = component.findComponent(UInput).get("input");
+
+      await input.trigger("focus");
+
+      expect(component.findComponent({ name: "UCalendar" }).props("dayClasses")).toBe(dayClasses);
+    });
+
     it("Custom Range Button – applies custom range button configuration", async () => {
       const customRangeButton = {
         range: { from: new Date("2023-01-01"), to: new Date("2023-01-31") },
@@ -440,6 +459,189 @@ describe("UDatePickerRange.vue", () => {
     });
   });
 
+  describe("Periods", () => {
+    const dataTest = "date-picker-range";
+    const menuPrefix = `${dataTest}-period-menu`;
+    const periodButtonNames: string[] = Object.values(Period).filter(
+      (type) => type !== Period.OwnRange && type !== Period.Custom,
+    );
+    const fullWeek: RangeDate = {
+      from: new Date(2023, 11, 4),
+      to: new Date(2023, 11, 10, 23, 59, 59),
+    };
+
+    async function mountOpened(props: Record<string, unknown>) {
+      const component = mount(UDatePickerRange, {
+        props: {
+          variant: "input",
+          dataTest,
+          modelValue: { from: null, to: null },
+          ...props,
+        },
+      });
+
+      await component.findComponent(UInput).get("input").trigger("focus");
+
+      return component;
+    }
+
+    function findPeriodButton(component: ReturnType<typeof mount>, name: string) {
+      return component.find(`[data-test="${menuPrefix}-period-${name}"]`);
+    }
+
+    function findOwnRangeButton(component: ReturnType<typeof mount>) {
+      return component.find(`[data-test="${menuPrefix}-own-range"]`);
+    }
+
+    function getRenderedPeriodNames(component: ReturnType<typeof mount>) {
+      return component
+        .findAll(`[data-test^="${menuPrefix}-period-"]`)
+        .map((button) => button.attributes("data-test")!.replace(`${menuPrefix}-period-`, ""))
+        .filter((name) => periodButtonNames.includes(name));
+    }
+
+    function isActive(button: ReturnType<ReturnType<typeof mount>["find"]>) {
+      return button.attributes("vl-key") === "periodButtonActive";
+    }
+
+    it("Periods – renders all period buttons and own range button by default", async () => {
+      const component = await mountOpened({});
+
+      expect(getRenderedPeriodNames(component)).toEqual(periodButtonNames);
+      expect(findOwnRangeButton(component).exists()).toBe(true);
+    });
+
+    it("Periods – renders only allowed period buttons without own range button", async () => {
+      const component = await mountOpened({ periods: ["month", "year"] });
+
+      expect(getRenderedPeriodNames(component)).toEqual(["month", "year"]);
+      expect(findOwnRangeButton(component).exists()).toBe(false);
+    });
+
+    it.each(["ownRange", "month"])(
+      "Periods – hides period switch when %s is the only period",
+      async (period) => {
+        const component = await mountOpened({ periods: [period] });
+
+        expect(getRenderedPeriodNames(component)).toEqual([]);
+        expect(findOwnRangeButton(component).exists()).toBe(false);
+      },
+    );
+
+    it("Periods – reduces range inputs top margin when period switch is hidden", async () => {
+      const component = await mountOpened({ periods: ["ownRange"] });
+      const rangeInputWrapper = component.get("[vl-key='rangeInputWrapper']");
+
+      expect(rangeInputWrapper.classes()).toContain("mt-2");
+      expect(rangeInputWrapper.classes()).not.toContain("mt-4");
+    });
+
+    it("Periods – removes range switch top padding when period switch is hidden", async () => {
+      const component = await mountOpened({ periods: ["month"] });
+
+      expect(component.get("[vl-key='rangeSwitchWrapper']").classes()).toContain("pt-0");
+    });
+
+    it("Periods – keeps range inputs top margin when period switch is shown", async () => {
+      const component = await mountOpened({});
+
+      expect(component.get("[vl-key='rangeInputWrapper']").classes()).toContain("mt-4");
+    });
+
+    it("Periods – shows own range button when custom range is also available", async () => {
+      const component = await mountOpened({
+        periods: ["ownRange"],
+        customRangeButton: {
+          range: { from: new Date(2023, 5, 1), to: new Date(2023, 5, 15) },
+          label: "First half of June",
+        },
+      });
+
+      expect(findOwnRangeButton(component).exists()).toBe(true);
+      expect(component.find(`[data-test="${menuPrefix}-custom-range"]`).exists()).toBe(true);
+    });
+
+    it("Periods – renders period buttons in canonical order", async () => {
+      const component = await mountOpened({
+        periods: ["year", "ownRange", "week", "quarter"],
+      });
+
+      expect(getRenderedPeriodNames(component)).toEqual(["week", "quarter", "year"]);
+      expect(findOwnRangeButton(component).exists()).toBe(true);
+    });
+
+    it("Periods – falls back to own range when model matches a disallowed period", async () => {
+      const component = await mountOpened({
+        periods: ["month", "ownRange"],
+        modelValue: fullWeek,
+      });
+
+      expect(findPeriodButton(component, "week").exists()).toBe(false);
+      expect(isActive(findOwnRangeButton(component))).toBe(true);
+      expect(isActive(findPeriodButton(component, "month"))).toBe(false);
+    });
+
+    it("Periods – falls back to the first allowed period when own range is not allowed", async () => {
+      const component = await mountOpened({
+        periods: ["year", "month"],
+        modelValue: fullWeek,
+      });
+
+      expect(isActive(findPeriodButton(component, "month"))).toBe(true);
+      expect(isActive(findPeriodButton(component, "year"))).toBe(false);
+    });
+
+    it("Periods – treats an empty array as all periods and warns", async () => {
+      const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+      const component = await mountOpened({ periods: [] });
+
+      expect(getRenderedPeriodNames(component)).toEqual(periodButtonNames);
+      expect(findOwnRangeButton(component).exists()).toBe(true);
+      expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('No valid "periods"'));
+
+      warnSpy.mockRestore();
+    });
+
+    it.each([
+      ["next", new Date(2023, 6, 1), new Date(2023, 6, 31)],
+      ["prev", new Date(2023, 4, 1), new Date(2023, 4, 31)],
+    ])(
+      "Periods – shifts custom range by the resolved period (%s)",
+      async (direction, expectedFrom, expectedTo) => {
+        const component = mount(UDatePickerRange, {
+          props: {
+            variant: "button",
+            dataTest,
+            periods: ["month", "year"],
+            modelValue: { from: null, to: null },
+            customRangeButton: {
+              range: { from: new Date(2023, 5, 1), to: new Date(2023, 5, 15) },
+              label: "First half of June",
+            },
+            "onUpdate:modelValue": (value: RangeDate) => {
+              component.setProps({ modelValue: value });
+            },
+          },
+        });
+
+        await component.get("[vl-key='rangeButtonSelect']").trigger("click");
+        await findPeriodButton(component, "year").trigger("click");
+        await component.get(`[data-test="${menuPrefix}-custom-range"]`).trigger("click");
+
+        await component.get(`[data-test="${dataTest}-button-${direction}"]`).trigger("click");
+
+        const { from, to } = component.props("modelValue") as {
+          from: Date;
+          to: Date;
+        };
+
+        expect(from.toDateString()).toBe(expectedFrom.toDateString());
+        expect(to.toDateString()).toBe(expectedTo.toDateString());
+      },
+    );
+  });
+
   describe("Menu", () => {
     it("Menu – opens when input is focused", async () => {
       const component = mount(UDatePickerRange, {

package/ui.form-date-picker-range/types.ts

@@ -1,5 +1,5 @@
 import defaultConfig from "./config";
-import { ShiftAction } from "./constants";
+import { ShiftAction, Period } from "./constants";
 
 import type { Ref } from "vue";
 import type { UnknownObject, ComponentConfig, GetDataTest } from "../types";
@@ -9,6 +9,7 @@ export type Locale = typeof defaultConfig.i18n;
 export type Config = typeof defaultConfig;
 export type IsDatePeriodOutOfRange = (datePeriod: DatePeriodRange) => boolean;
 export type ShiftActions = `${ShiftAction}`;
+export type PeriodType = `${Period}`;
 
 export interface SortedLocale extends Omit<Locale, "weekdays" | "months"> {
   months: {
@@ -53,6 +54,8 @@ export interface UDatePickerRangePeriodMenuProps {
   locale: SortedLocale;
   dateFormat: string | undefined;
   isPeriod: IsPeriod;
+  allowedPeriods: readonly Period[];
+  isPeriodSwitchShown: boolean;
   maxDate: string | Date | undefined;
   minDate: string | Date | undefined;
   customRangeButton: CustomRangeButton;
@@ -122,6 +125,11 @@ export interface Props<TModelValue> {
    */
   customRangeButton?: CustomRangeButton;
 
+  /**
+   * Period types available for selection.
+   */
+  periods?: PeriodType[];
+
   /**
    * Datepicker open direction on x-axis.
    * @extendOnly
@@ -179,6 +187,11 @@ export interface Props<TModelValue> {
    */
   rightIcon?: string;
 
+  /**
+   * Extra CSS classes to apply to each day cell, on top of the built-in state classes.
+   */
+  dayClasses?: (day: Date) => string;
+
   /**
    * Unique element id.
    */