@boobooking/dashboard-ui-components 0.1.0 → 0.2.0

package/README.md

@@ -31,33 +31,38 @@ Tailwind, `@tailwindcss/forms`, Inertia и какие-либо токены в C
 ### Popup
 
 Всплывающее меню с оверлеем, закрывающим по клику вне, и переходом на
-открытие/закрытие. `PickDay` и `SelectSingle` держат его внутри как обёртку
-над своим содержимым.
+открытие/закрытие. Другие компоненты пакета используют его как обёртку над
+своим содержимым — некоторые напрямую, некоторые через внутренние
+компоненты.
 
-    <popup v-model:is-open="isOpen" align="right">
+    <popup v-model="isOpen" align="right">
         …содержимое меню…
     </popup>
 
 | Проп | Тип | По умолчанию | Описание |
 | --- | --- | --- | --- |
-| `isOpen` | `Boolean` | `false` | Открыто ли меню |
+| `modelValue` | `Boolean` | `false` | Открыто ли меню |
 | `align` | `String` | `"left"` | `"left"` или `"right"` — с какой стороны прижать меню |
 
-Событие: `update:isOpen` — при каждом открытии и закрытии, включая клик по
+Событие: `update:modelValue` — при каждом открытии и закрытии, включая клик по
 оверлею.
 
+У `Popup` нет события `changed`, и это не пропуск — см. раздел
+«Почему у Popup и Dot нет события changed».
+
 ### Dot
 
 Индикатор-точка: красная или зелёная, с пульсацией или без.
 
-    <dot color="green" :add-pulse="isLive" />
+    <dot color="green" :with-pulse="isLive" />
 
 | Проп | Тип | По умолчанию | Описание |
 | --- | --- | --- | --- |
 | `color` | `String` | обязателен | `"red"` или `"green"` |
-| `addPulse` | `Boolean` | `false` | Добавляет анимацию пульсации |
+| `withPulse` | `Boolean` | `false` | Добавляет анимацию пульсации |
 
-Событий нет.
+Событий нет. Значения у `Dot` тоже нет — см. раздел
+«Почему у Popup и Dot нет события changed».
 
 ### PickDay
 
@@ -67,7 +72,7 @@ Tailwind, `@tailwindcss/forms`, Inertia и какие-либо токены в C
 
 | Проп | Тип | По умолчанию | Описание |
 | --- | --- | --- | --- |
-| `modelValue` | `String` | обязателен | Текущая дата |
+| `modelValue` | `String` | `""` | Текущая дата |
 | `withEraser` | `Boolean` | `true` | Показывать ли ластик очистки |
 | `placeholderText` | `String` | `""` | Текст подсказки в пустом поле |
 
@@ -128,15 +133,12 @@ Tailwind, `@tailwindcss/forms`, Inertia и какие-либо токены в C
 
 | Проп | Тип | По умолчанию | Описание |
 | --- | --- | --- | --- |
-| `dateFrom` | `String` | обязателен | Начало интервала |
-| `dateTo` | `String` | обязателен | Конец интервала |
+| `dateFrom` | `String` | `""` | Начало интервала |
+| `dateTo` | `String` | `""` | Конец интервала |
 | `header` | `String` | обязателен | Подпись поля |
 | `isRequired` | `Boolean` | `false` | Пометка обязательности в заголовке |
 | `isLoading` | `Boolean` | `false` | Индикатор загрузки в заголовке |
 
-`dateFrom` и `dateTo` обязательны без умолчания — потребитель должен
-передавать обе даты явно.
-
 События: `update:dateFrom`, `update:dateTo` — на каждый выбор в
 соответствующем `PickDay`; `changed` — когда новое значение отличается от
 переданного пропса (отдельно для каждой из двух дат).
@@ -164,6 +166,45 @@ Tailwind, `@tailwindcss/forms`, Inertia и какие-либо токены в C
 События: `update:modelValue` и `changed` — при выборе элемента (повторный
 клик по уже выбранному снимает выбор) и при очистке через ластик.
 
+## Правила API пакета
+
+Компонент, добавляемый в пакет, следует тем же правилам, что и уже
+имеющиеся:
+
+- Значение компонента передаётся через `v-model` (проп `modelValue` и
+  событие `update:modelValue`) и не обязательно: компонент обязан
+  отрисовываться без переданного значения. `required: true` оставляют
+  только там, без чего компонент бессмыслен, — например, у `items` в
+  `SelectSingle` или у `header` во всех фильтрах.
+- Именованные модели (`v-model:date-from`, `v-model:date-to`, как у
+  `SelectDateInterval`) — исключение для компонентов с несколькими
+  значениями. У компонента с одним значением именованная модель не нужна:
+  для него это и есть обычный `v-model`.
+- Булев проп называется `is*`, если описывает состояние компонента
+  (`isRequired`, `isLoading`), и `with*`, если описывает необязательную
+  возможность (`withEraser` у `PickDay`, `withPulse` у `Dot`).
+- Проп-перечисление — ограниченный набор строковых значений, как `color` у
+  `Dot` или `align` у `Popup`, — обязательно имеет `validator`,
+  отклоняющий значения вне списка.
+
+## Почему у Popup и Dot нет события changed
+
+`changed` означает не «значение изменилось», а «пользователь закончил
+выбор, можно обновлять выдачу» — фильтры дашборда эмитят его как сигнал к
+перезапросу данных.
+
+У `Popup` такого момента нет: он не хранит значение фильтра, а лишь
+управляет видимостью меню, и открытие меню — не повод перезагружать
+данные. Момент, когда выбор действительно завершён, отслеживает
+компонент, который использует `Popup` — сам или через внутренние
+компоненты пакета, — `changed` эмитит он.
+
+У `Dot` события нет по другой причине: у него нет значения вообще, поэтому
+эмитить не о чем.
+
+Отсутствие `changed` у `Popup` и `Dot` — сознательное решение, а не
+пропуск.
+
 ## Playground
 
     npm run playground

package/dist/index.js

@@ -49,26 +49,27 @@ function C(e, t, n, r, a, o) {
 var w = {
 	components: { Overlay: /* @__PURE__ */ x(S, [["render", C]]) },
 	inheritAttrs: !1,
-	emits: ["update:isOpen"],
+	emits: ["update:modelValue"],
 	props: {
-		isOpen: {
+		modelValue: {
 			type: Boolean,
 			default: !1
 		},
 		align: {
 			type: String,
-			default: "left"
+			default: "left",
+			validator: (e) => ["left", "right"].indexOf(e) !== -1
 		}
 	},
 	data() {
-		return { overlayIsOpen: this.isOpen };
+		return { overlayIsOpen: this.modelValue };
 	},
 	watch: {
-		isOpen: function(e) {
+		modelValue: function(e) {
 			this.overlayIsOpen = e;
 		},
 		overlayIsOpen(e) {
-			this.$emit("update:isOpen", e);
+			this.$emit("update:modelValue", e);
 		}
 	},
 	computed: {
@@ -96,13 +97,13 @@ function E(e, n, r, c, u, p) {
 		default: g(() => [_(a("div", s(e.$attrs, { class: ["absolute z-20", {
 			"left-0": p.alignLeft,
 			"right-0": p.alignRight
-		}] }), [d(e.$slots, "default")], 16), [[h, r.isOpen]])]),
+		}] }), [d(e.$slots, "default")], 16), [[h, r.modelValue]])]),
 		_: 3
 	})]);
 }
 var D = /*#__PURE__*/ x(w, [["render", E]]), O = {
 	props: {
-		addPulse: {
+		withPulse: {
 			type: Boolean,
 			default: !1
 		},
@@ -125,7 +126,7 @@ function te(e, t, n, r, o, s) {
 	return l(), i("div", { class: c(["bb-dashboard-ui flex h-full items-center leading-none text-4xl", {
 		"text-red-500": s.isRed,
 		"text-green-500": s.isGreen,
-		"animate-pulse": n.addPulse
+		"animate-pulse": n.withPulse
 	}]) }, [...t[0] ||= [a("svg", {
 		class: "fill-current w-2 h-2",
 		viewBox: "0 0 120 120"
@@ -175,7 +176,7 @@ var I = {
 	props: {
 		modelValue: {
 			type: String,
-			required: !0
+			default: ""
 		},
 		withEraser: {
 			type: Boolean,
@@ -299,12 +300,12 @@ function H(e, t, s, u, d, p) {
 		onClick: p.clearPicker,
 		class: "z-10 h-full pr-2"
 	}, null, 8, ["onClick"])) : r("", !0)]), o(h, {
-		"is-open": d.popupIsOpen,
-		"onUpdate:isOpen": t[1] ||= (e) => d.popupIsOpen = e
+		modelValue: d.popupIsOpen,
+		"onUpdate:modelValue": t[1] ||= (e) => d.popupIsOpen = e
 	}, {
 		default: g(() => [a("div", V, null, 512)]),
 		_: 1
-	}, 8, ["is-open"])]);
+	}, 8, ["modelValue"])]);
 }
 var U = /*#__PURE__*/ x(I, [["render", H]]), W = {
 	components: { Dot: k },
@@ -332,7 +333,7 @@ function q(e, t, n, r, s, c) {
 		}, null, 8, K),
 		_(o(u, {
 			color: "red",
-			"add-pulse": !0,
+			"with-pulse": !0,
 			class: "ml-3"
 		}, null, 512), [[h, n.isLoading]]),
 		_(o(u, {
@@ -548,11 +549,11 @@ var _e = /*#__PURE__*/ x(de, [["render", ge]]), ve = {
 	props: {
 		dateFrom: {
 			type: String,
-			required: !0
+			default: ""
 		},
 		dateTo: {
 			type: String,
-			required: !0
+			default: ""
 		},
 		header: {
 			type: String,
@@ -659,12 +660,12 @@ function Oe(e, t, s, u, m, h) {
 		onClick: t[1] ||= (t) => e.$emit("erased"),
 		class: "pr-2 h-full"
 	})) : r("", !0)]), o(v, {
-		"is-open": m.popupIsOpen,
-		"onUpdate:isOpen": t[2] ||= (e) => m.popupIsOpen = e
+		modelValue: m.popupIsOpen,
+		"onUpdate:modelValue": t[2] ||= (e) => m.popupIsOpen = e
 	}, {
 		default: g(() => [d(e.$slots, "default")]),
 		_: 3
-	}, 8, ["is-open"])]);
+	}, 8, ["modelValue"])]);
 }
 var ke = /*#__PURE__*/ x(Te, [["render", Oe]]), Ae = {
 	props: {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@boobooking/dashboard-ui-components",
-    "version": "0.1.0",
+    "version": "0.2.0",
     "description": "Компоненты фильтров дашборда на Vue 3",
     "keywords": [
         "vue",