deckz:0.3.1 (#3106)

Author: micheledusi

packages/preview/deckz/0.3.1/LICENSE

@@ -0,0 +1,95 @@
+#import "../template.typ": *
+
+// Complete documentation for DECKZ functions and features
+= Documentation
+<sec:documentation>
+
+
+== Card visualization
+This section provides a comprehensive overview of the DECKZ package's *card visualization* capabilities. It presents the available formats and how to use them effectively.
+#show-module(("view/format", "view/back"))
+
+
+#pagebreak()
+== Group visualization
+This section covers the *group visualization* features of the DECKZ package, i.e. all functions that allow you to visualize groups of cards, such as hands, decks, and heaps.
+#show-module("view/group")
+
+
+#pagebreak()
+== Data
+This section provides an overview of the *data structures* used in the DECKZ package, including suits, ranks, and cards. It explains how these data structures are organized and how to access them.
+#show-module(("data/suit", "data/rank", "logic/structs"))
+//#show-module("data/style")
+
+
+#pagebreak()
+== Randomization
+The DECKZ package includes essential *randomization features* for card games, such as shuffling and drawing random cards from a deck. However, since *Typst* is a pure functional language, true randomness is not available; instead, DECKZ uses the #universe("suiji") package to generate pseudo-random numbers.
+
+This section explains how to use these randomization tools within DECKZ, describes the underlying concepts, and provides practical guidance for integrating randomness into your projects.
+Randomization functions are available under the #primary[`deckz.mix`] namespace, and they include:
+#show-module("logic/mix", submodule: "mix")
+
+#pagebreak()
+== Arranging hands
+This section covers the *sorting and organizing functions* available in the #primary[`arr`] module in the DECKZ package.
+It explains how to sort cards by rank, suit, and other criteria, providing a foundation for building more complex card games and applications.
+#show-module("logic/sort", submodule: "arr")
+
+
+#pagebreak()
+== Evaluating hands
+This section provides an overview of the *scoring functions* from the #primary[`val`] module of the DECKZ package, which are essential for evaluating hands in card games. Such functions are helpful for assessing the value of a hand based on various criteria and combinations, such as n-of-a-kind, flushes, and straights.
+#show-module("logic/score", submodule: "val")
+
+
+#pagebreak()
+== Language-aware card symbols
+DECKZ automatically adapts the rendering of card rank symbols based on the document's language. This process is seamless: users only need to set the desired language using the `text` command, and DECKZ will adjust the symbols accordingly. No additional configuration is required.
+
+#let build-lang-row(lang) = {
+	return (
+		text(weight: "bold")[
+			#primary(smallcaps(lang))
+		],
+		..deckz.ranks.values().map(rank-data => [
+				#set text(lang: lang)
+				#text(size: 1.2em, weight: "medium", rank-data.symbol)
+				#linebreak()
+				#text(size: 0.5em)[#rank-data.name]
+			]),
+	)
+}
+
+The current version of DECKZ supports the following *languages*:
+
+#show table.cell: set align(center)
+#show table.cell: set text(font: "Roboto Slab", size: 0.9em)
+#table(
+	stroke: gray.transparentize(70%) + 1pt,
+	columns: (1cm, ) + (1fr,) * 13,
+	..build-lang-row("en"),
+	..build-lang-row("it"),
+	..build-lang-row("fr"),
+	..build-lang-row("de"),
+	..build-lang-row("ru"),
+)
+
+The localization is powered by the #universe("linguify") package, thanks to the generous contribution of the users who helped translating card names and symbols.
+
+#example(breakable: true, side-by-side: true)[
+	```typ
+	#let seq = ("10C", "JH", "QS", "KD", "AC")
+
+	#set text(lang: "en")
+	#deckz.line(..seq, format: "small")
+
+	#set text(lang: "it")
+	#deckz.line(..seq, format: "small")
+
+	#set text(lang: "fr")
+	#deckz.line(..seq, format: "small")
+	```
+]
+

packages/preview/deckz/0.3.1/README.md

@@ -0,0 +1,31 @@
+#let cards-window(body) = block(fill: white, width: 100%, inset: 5pt, body)
+
+#block(fill: gray.lighten(60%), inset: 5pt, breakable: false)[
+
+  #let example-cards = ("AS", "5H", "10C", "QD")
+
+  #text(blue)[`inline`] --- A minimal format where the rank and suit are displayed directly within the flow of text; perfect for quick references.
+  #cards-window[
+    #deckz.line(..example-cards, format: "inline", width: 100%)
+  ]
+
+  #text(blue)[`mini`] --- The smallest visual format: a compact rectangle showing the rank at the top and the suit at the bottom.
+  #cards-window[
+    #deckz.line(..example-cards, format: "mini", width: 100%)
+  ]
+
+  #text(blue)[`small`] --- A slightly larger card with rank indicators on opposite corners and a central suit symbol; ideal for tight layouts with better readability.
+  #cards-window[
+    #deckz.line(..example-cards, format: "small", width: 100%)
+  ]
+
+  #text(blue)[`medium`] --- A fully structured card layout featuring proper suit placement and figures. Rank and suit appear in two opposite corners, offering a realistic visual.
+  #cards-window[
+    #deckz.line(..example-cards, format: "medium", width: 100%)
+  ]
+
+  #text(blue)[`large`] --- The most detailed format, with corner summaries on all four corners and an expanded layout; great for presentations or printable decks.
+  #cards-window[
+    #deckz.line(..example-cards, format: "large", width: 100%)
+  ]
+]

packages/preview/deckz/0.3.1/docs/documentation/index.typ

@@ -0,0 +1,51 @@
+#let player-mat(body) = box(
+  stroke: olive.darken(20%),
+  fill: olive.lighten(10%),
+  radius: (top: 50%, bottom: 5%), 
+  inset: 15%,
+  body
+)
+
+#text(white, font: "Roboto Slab", weight: "semibold")[
+  #box(fill: olive, 
+    width: 100%, height: 12cm, 
+    inset: 4mm, radius: 2mm
+  )[
+
+    #place(center + bottom)[
+      #player-mat[
+        #deckz.hand(format: "small", width: 3cm, "9S", "10H", "4C", "4D", "2D")
+        Alice
+      ]
+    ]
+    #place(left + horizon)[
+      #rotate(90deg, reflow: true)[
+        #player-mat[
+          #deckz.hand(format: "small", width: 3cm, "AS", "JH", "JC", "JD", "3D")
+          #align(center)[Bob]
+        ]
+      ]
+    ]
+    #place(center + top)[
+      #rotate(180deg, reflow: true)[
+        #player-mat[
+          #deckz.hand(format: "small", width: 3cm, "KH", "8H", "7H", "5C", "3C")
+          #rotate(180deg)[Carol]
+        ]
+      ]
+    ]
+    #place(right + horizon)[
+      #rotate(-90deg, reflow: true)[
+        #player-mat[
+          #deckz.hand(format: "small", width: 3cm, "6S", "3H", "2H", "QC", "9C")
+          #align(center)[Dave]
+        ]
+      ]
+    ]
+    #place(center + horizon)[
+      #deckz.deck(format: "small", angle: 80deg, height: 8mm, "back")
+    ]
+  ]
+]
+
+In this situation, Alice has a *Pair of Four* (#deckz.inline("4C"), #deckz.inline("4D")). _What should the player do?_

packages/preview/deckz/0.3.1/docs/examples/exmp_comparison_table.typ

@@ -0,0 +1,12 @@
+#text(white, font: "Oldenburg", size: 10pt)[
+  #block(fill: aqua.darken(40%), inset: 4mm, radius: 2mm)[
+    #deckz.hand(
+      angle: 270deg, 
+      width: 5.8cm, 
+      format: "large", 
+      noise: 0.05, 
+      ..deckz.deck52
+    )
+    #place(center + horizon)[#text(size: 20pt, baseline: 8pt)[Deckz]]
+  ]
+]

packages/preview/deckz/0.3.1/docs/examples/exmp_current_state.typ

@@ -0,0 +1,87 @@
+// Defining players and their hands
+#let players = ("Alice", "Bob", "Carol", "David")
+#let (players-hands, board-cards) = deckz.mix.split(
+  deckz.deck52, // Start with a standard deck of 52 cards
+  size: ((players.len(), 2), 5), // 2 cards per player + 5 board cards
+  rest: false,
+)
+
+#set align(center)
+#set text(fill: white, size: 13pt, font: "Arvo")
+
+#block(
+  fill: olive,
+  inset: 15pt,
+  radius: 5pt,
+  breakable: false,
+)[
+  // Board cards
+  *Board*
+  #deckz.hand(
+    format: "small",
+    width: 4cm,
+    angle: 20deg,
+    noise: 0.2,
+    ..board-cards
+  )
+  // Displaying the deck of cards
+  #place(right + top)[
+    #deckz.deck(
+      format: "small",
+      angle: 90deg,
+      noise: 0.2,
+      "back"
+    )
+  ]
+  
+  #v(1cm)
+  #set table.cell(
+    fill: olive.darken(20%),
+    stroke: olive.darken(10%) + 2pt,
+  )
+
+  // Players' hands
+  #table(
+    columns: players.len(),
+    column-gutter: 1fr,
+
+    ..players-hands
+      .zip(players)
+      .map(((hand, player)) => [
+        #player
+        #deckz.hand(
+          format: "small",
+          width: 1cm,
+          angle: 30deg,
+          noise: 0.4,
+          ..hand
+        )
+      ])
+  )
+]
+
+#set align(left)
+#set text(fill: black, size: 12pt)
+
+Which is the *best hand* each player can make?
+#for (player, hand) in players.zip(players-hands) [
+
+  - *#player*
+  #box(
+    fill: olive,
+    inset: 8pt,
+    radius: 15%,
+  )[
+    #(hand + board-cards).map(deckz.mini).join("  ")
+  ]
+  $stretch(=>)^"  Best hand  "$
+  #let best = deckz.val.extract-highest(hand + board-cards, sort: true).first()
+  #box(
+    fill: none, 
+    stroke: (paint: green, thickness: 3pt, dash: "dashed"), 
+    inset: 8pt, 
+    radius: 45%,
+  )[
+    #best.map(deckz.mini).join("  ")
+  ]
+]

packages/preview/deckz/0.3.1/docs/examples/exmp_deck_circle.typ

@@ -0,0 +1,43 @@
+// Define and sort the initial hand
+#let my-hand = deckz.arr.sort-by-score(("8S", "9S", "10S", "JS", "QS", "9H", "9D", "9C", "QD", "3D", "4D", "5D"))
+
+#set text(font: "Roboto Slab")
+My current *hand*: 
+
+#deckz.hand(..my-hand,
+	format: "small",
+	angle: 10deg,
+	width: 12cm,
+)
+
+#let show-combination(combination) = [
+	
+	Which *#combination* can I make?
+
+	#let combinations = deckz.val.extract(combination, my-hand)
+	#if combinations.len() == 0 {
+	 	[None.]
+	} else {
+		for combo in combinations {
+			box(
+				fill: eastern,
+				inset: 6pt, 
+				radius: 12pt,
+			)[
+				#deckz.line(..combo, format: "mini", spacing: 6pt)
+			]
+			h(1mm)
+		}
+	}
+]
+ 
+#show-combination("high-card")
+#show-combination("pair")
+#show-combination("two-pairs")
+#show-combination("three-of-a-kind")
+#show-combination("straight")
+#show-combination("flush")
+#show-combination("full-house")
+#show-combination("four-of-a-kind")
+#show-combination("straight-flush")
+#show-combination("five-of-a-kind")

packages/preview/deckz/0.3.1/docs/examples/exmp_game_random.typ

@@ -0,0 +1,66 @@
+#import "../template.typ": *
+
+// Examples of how to use DECKZ
+= Examples
+<sec:examples>
+
+
+The following examples showcase more advanced and interesting *use cases* of DECKZ. In this Section, you can find how DECKZ can be used to represent real game states, compare card formats, and display entire decks in creative ways.
+
+== Displaying the current state of a game
+
+You can use DECKZ to display the *current state of a game*, such as the cards in hand, the cards on the table, and the deck.
+
+#example(breakable: true)[
+	#raw(
+		lang: "typ",
+		read("exmp_current_state.typ"),
+	)
+]
+
+#pagebreak()
+== Comparing different formats
+
+You can use DECKZ to *compare different formats* of the same card, or to show how a card looks in different contexts.
+
+#example(breakable: true)[
+	#raw(
+		lang: "typ",
+		read("exmp_comparison_table.typ"),
+	)
+]
+
+#pagebreak()
+== Displaying a full deck
+
+You can use DECKZ to display a *full deck of cards*, simply by retrieving the `deckz.deck52` array, which contains all 52 standard playing cards.
+
+#example(breakable: true)[
+	#raw(
+		lang: "typ",
+		read("exmp_deck_circle.typ"),
+	)
+]
+
+#pagebreak()
+== Randomized game with card scoring
+
+You can use DECKZ to create a *randomized _Texas Hold'em_-like game*, where players are dealt random hands and their best hands are determined based on the cards on the table/*, using the @cmd:deckz:val:extract-highest function*/.
+
+#example(breakable: true)[
+	#raw(
+		lang: "typ",
+		read("exmp_game_random.typ"),
+	)
+]
+
+#pagebreak()
+== Scoring hands
+You can use DECKZ to *score hands* in a game, such as Poker, by extracting combinations of cards that form specific hands, such as pairs, three-of-a-kinds, straights, flushes, and so on.
+
+#example(breakable: true)[
+	#raw(
+		lang: "typ",
+		read("exmp_scoring.typ"),
+	)
+]